Implementation Guide - Transaction and Activity monitoring

Prerequisites

curl --location '[https://api.uat.frankie.one/v2/kyc/ruok](https://api.uat.frankie.one/v2/kyc/ruok)' \--header 'api_key: {{your_uat_api_key}}' \--header 'X-Frankie-CustomerId: {{your_uat_customer_id}}'

curl --location '[https://api.uat.frankie.one/v2/workflows](https://api.uat.frankie.one/v2/workflows)' \--header 'api_key: {{your_uat_api_key}}' \--header 'X-Frankie-CustomerId: {{your_uat_customer_id}}'

{
  "requestId": "req_01J...",
  "workflows": [
    {
      "serviceName"   : "KYC",
      "workflowId"    : "wf_01J...",
      "workflowName"  : "Monitoring",
      "type"          : "SYSTEM",
      "lifecyclePhase": "MONITORING",
      "monitoringTypes": ["ACTIVITY"]
    }
  ]
}

Next Steps

You’ve successfully authenticated and confirmed your setup. Now you’re ready to start building. Follow our implementation guides for common use cases.

Integration Overview

Getting started with Transaction and Activity Monitoring

1: Use the Transaction and Activity Monitoring API

Start sending transaction and activity details to FrankieOne by calling Evaluate an activity endpoint

curl --location 'localhost:8103/v2/activities' \
--header 'X-Frankie-CustomerID: 3d6d52a5-aed0-4f22-86c0-4d78ae1e807a' \
--header 'api_key: X' \
--header 'Content-Type: application/json' \
--data '{
    "activity": {
        "session": {
            "token": "'"$TOKEN"'"
        },
        "party": {
            "entityId": "'"c5cd506d-9402-465c-a695-c800e4d8e330"'",
            "entityType": "INDIVIDUAL"
        },
        "detail": {
            "customAttributes": {
                "transactionRiskScore": {
                  "type": "NUMBER",
                  "value": "750" 
                },
                "purposeOfTransaction": {
                  "type": "STRING",
                  "value": "International property purchase"
                },
                "sourceOfFunds": {
                  "type": "STRING",
                  "value": "Savings from employment"
                }
            },
            "activityType": "TRANSACTION",
            "activityAt": "2025-09-02T05:38:02.000360071+00:00",
            "transaction": {
                "amount": 200000.00,
                "currency": "AUD",
                "currencyType": "FIAT",
                "transferMethod": "BANK_TRANSFER",
                "counterpartyAmount": 200000.00,
                "counterpartyCurrency": "AUD",
                "counterpartyCurrencyType": "FIAT",
                "counterpartyTransferMethod": "BANK_TRANSFER",
                "transactionType": "WITHDRAWAL",
                "description": "Payment for real estate in New York",
                "account": {
                    "type": "SAVINGS",
                    "pan": "331387321",
                    "hashedPan": "763d54d45eada3bd9431541d8478caea5d39027fe6e7211de67ac7ddf680092a",
                    "maskedPan": "******321",
                    "name": "super saver",
                    "class": "PERSONAL",
                    "externalIdentifier": "089217ASIJI99",
                    "externalIdentifierType": "EXTERNAL_ID_NUMBER"
                },
                "merchant": {
                    "merchantIdentifier": "REALESTATEINC001",
                    "industryCodes": [
                        {
                            "code": "6513",
                            "description": "Real Estate Agents and Managers",
                            "type": "MCC"
                        }
                    ]
                },
                "transactionIdentifier": "'"$TRANSACTION_ID"'"
            },
            "counterparty": {
                "entityName": "Global Property Investments LLC",
                "account": {
                    "type": "SAVINGS",
                    "pan": "123783133",
                    "hashedPan": "96b5c78f239e5d4b408ff0d934f7e6a930b2072e16461ebec57607ba16985643",
                    "maskedPan": "******133",
                    "name": "Property Sales Account",
                    "class": "BUSINESS"
                }
            }
        }
    }
}'

High-level process flow

Activity evaluation

1. Customer sends transaction / activity data to FrankieOne.

2. FrankieOne will pass the activity data to the service provider

   • Frankie checks the entity data store and enrich the customer request with additional data
   • Frankie enriches the activity data to the service provider, handling mapping between models

3. Vendor assesses the data provided against Customer rules to make a point-in-time evaluation of the activity risk.

   • All risks, rules checked and additional evaluation data are returned to FrankieOne
   • FrankieOne maps vendor data back to common model

4. FrankieOne will persist the resulting evaluation information

   1. Create the activity record

      1. Create the device data retrieved from the provider

         1. Store the evaluation data (risk, signals etc)
      2. Return the evaluation data to the customer for a final risk-based decisioning

   2. Asynchronous Enhanced Processing – Push an activity event to the internal message queue for enhanced processing

      1. The event message is consumed by the internal activity assessment service.
      2. If the activity does not meet the risk criteria to trigger an alert or further assessment, then no further action is taken.
      3. If the activity does meet the risk criteria for an alert, it will retrieve the activity data, and create an assessment result which represents the alert details.
      4. Once done, it will push a message into the workflow engine message queue to trigger relevant monitoring workflows.
      5. Inside the monitoring workflow, the Activity Monitor Step will consume relevant results to build up a view of alerts that should be actioned.
      6. This workflow will also generate risk assessments that combine risk factors across the onboarding and monitoring life cycle phases of the relevant entity.

The session object

Provides a token to link together activities within the same end-user session. This is important for identifying grouped activities and contributes to risk calculations by allowing FrankieOne to analyze a sequence of user actions as a single, coherent session. For example, all actions from a user login to a significant transaction can be linked together. The session token may be provided to tie in the activity to a longer running overall session. There are a few options for session tokens, including generating one via Create Individual Session or passing an existing one from your system.

The party object

Identifies the individual or organization performing the activity. It’s essential for linking the activity to an existing entity in FrankieOne. Key details include:

• entityId: The unique identifier for the individual or organization in FrankieOne.

• entityType: Specifies whether the party is an INDIVIDUAL or ORGANIZATION.

Additional details like addresses, emailAddresses, phoneNumbers, and externalReference (e.g. customer ID in your core banking system) help to give context the party’s profile for more accurate risk assessment.

The details object

Contains specific information about the activity being evaluated.

• activityType: Categorizes the activity broadly (e.g. TRANSACTION, EVENT).

• eventType: Provides a more granular classification of the activity (e.g. LOGIN, WITHDRAWAL, DEPOSIT, PASSWORD_CHANGE). This is critical for triggering specific rules relevant to the event.

• activityAt: Timestamp of the activity.

• customAttributes: Allows you to pass any additional context-specific data that might be relevant for your custom rules.

These objects are further detailed in the API documentation.

2: Review alerts

Once an activity has been deemed to be alerting, relevant workflows will be triggered and the alerts will be consumed and presented in the workflowResult object. This object is the key to understanding the outcome, the reason for any alerts, and the granular details of the checks performed. Operators will typically review these alerts via the Portal, where issues are flagged for manual review.

via API

Get the result of the evaluation by calling the Get Workflow Execution Results endpoint. The workflowResult object in the response will contain the comprehensive details needed to interpret the outcome.

curl https://api.uat.frankie.one/v2/individuals/entityId/serviceprofiles/serviceName/workflows/workflowName/executions/workflowExecutionId \
     -H "api_key: X" \
     -H "X-Frankie-CustomerID: 12345678-1234-1234-1234-123456789012"

via Portal

To learn how Fraud and Compliance Officers can review alerts generated via Portal here, review Entity View.

Interpreting the results

The workflowResult object provides a structured, top-down view of the evaluation. Here’s how to interpret the key sections, focusing on Transaction and Activity Monitoring:

Overall outcome (workflowResult top-level fields)

API	Portal
workflowExecutionState: This confirms the workflow’s technical status. It must be COMPLETED for the status to be considered final and for you to reliably review the activity’s details. Other states like IN_PROGRESS, ERROR, TIMEOUT, CANCELED, or TERMINATED indicate the workflow did not finish successfully.	Not displayed in Portal
status : This represents a conclusive recommendation (configured status in your selected workflow) for the activity after evaluation and accounts for any manual overrides. For monitoring workflows, common/preferred statuses include - CLEAR (no negative information found) - REVIEW (requires manual review due to identified issues)	No issues (CLEAR) Needs attention (REVIEW)
result: This field holds the original, automated outcome of the workflow before any manual changes. It is useful for auditing and understanding the system’s initial verdict versus any human intervention.	Not displayed in Portal

Issues

This array will contain a list of problems that may require manual review. If the status is REVIEW, this array will provide the specific reasons why the activity needs further investigation.

For Transaction and Activity Monitoring, this might include flags of different types for unusual transaction patterns, device anomalies, or AML concerns with issueCategory: ACTIVITY. The Portal will display these as “Activity” as seen in the image below.

Entities flagged with issue Activity

Workflow step results

The workflowStepResults array is a log of each step in the workflow, explaining how the overall status was reached. Each object in this array corresponds to a step configured in your monitoring workflow (e.g. AML check, device check, transaction velocity check).

{
    "amlActivityCount": 3,
    "amlActivityTruePositiveCount": 0,
    "eventActivityCount": 0,
    "eventActivityTruePositiveCount": 0,
    "fraudActivityCount": 0,
    "fraudActivityTruePositiveCount": 0,
    "stepName": "ACTIVITY_MONITOR"
}

Activity alerts

For the deepest level of detail, look inside a workflowStepResult at its processResults array. A Process Result Object (PRO) is the raw evidence from a single check against a single data source (e.g., a specific device fingerprint provider, an AML watchlist provider).

• processResultId: A unique identifier for this specific piece of evidence.

• systemStatus: The lifecycle status of this PRO (e.g., VALID, STALE, MARKED_INVALID). A STALE status means the underlying entity data has changed since this check was performed and it might need re-evaluation. Only the alerts with a systemStatus: VALID will be displayed in Portal.

• class: The high-level category of the check performed, for Transaction and Activity Monitoring, it’s ACTIVITY.

• objectType: The specific data element that was checked (e.g., INDIVIDUAL, TRANSACTION, DEVICE).

• result: The outcome of this specific PRO (e.g., MATCH for a hit, CLEAR for no hit, CREATED for data fetched).

• manualStatus: If an operator has manually reviewed this specific PRO, their conclusion (e.g., TRUE_POSITIVE, FALSE_POSITIVE, IN_REVIEW) is recorded here. This is directly linked to the statuses described in Section 3.

• providerResult: An object containing details from the downstream data provider, including the source of the data.

• supplementaryData: A rich, context-specific object containing detailed metrics or extracted data, like AML hits details or specific device intelligence data. This is where most of the alerts or rows in the table gets its details as seen in the Portal.

3: Resolve alerts

Portal display	API manualStatus	Description
Needs attention	Null	Indicates that the alert requires review and resolution.
In review	IN_REVIEW	Indicates that the alert is being actively investigated or reviewed.
True positive: Reject	TRUE_POSITIVE_REJECT	Indicates that the activity was confirmed or suspected to be fraudulent or high-risk, and the associated activity was rejected (e.g. transaction blocked).
True positive: Accept	TRUE_POSITIVE_ACCEPT	Indicates that the activity was confirmed or suspected to be fraudulent or high-risk, and the associated activity was accepted (e.g. transaction approved with override).
False positive	FALSE_POSITIVE	Indicates the alert was reviewed, and confirmed or assumed to be genuine or low-risk.

via API

Given the activity results update its status by calling Update Activity results endpoint

curl -X 'PATCH' \
  'localhost:8103/v2/individuals/819011ac-6f61-4a79-87e1-70851cdb69ac/results/activity' \
  -H 'accept: application/json' \
  -H 'api_key: X' \
  -H 'X-Frankie-CustomerID: 3d6d52a5-aed0-4f22-86c0-4d78ae1e807a' \
  -H 'X-Frankie-Username: fred.flintstone@frankieone.com' \
  -H 'Content-Type: application/json' \
  -d '{
  "processResults": [
    "01K9DYRS7PYYZXRCS62SE7KTWG"
  ],
  "manualStatus": "TRUE_POSITIVE_ACCEPT",
  "comment": {
    "text": "Update after speaking to customer over the phone directly.",
    "entityId": "819011ac-6f61-4a79-87e1-70851cdb69ac",
    "entityType": "INDIVIDUAL"
  }
}'

via Portal

Features

4: Re-evaluate the results

Once all alerts have been resolve, you must re-run the workflow for the entity.

1. To update the status: The overall workflowResult.status will only be changed by the system from REVIEW to PASS or CLEAR after the workflow is executed again and the steps included in the monitoring workflow confirms that no unresolved hits remain.

2. To clear issues: The re-execution will cause the steps to re-evaluate the issues. If all PROs that previously caused an ACTIVITY issue are now classified as FALSE_POSITIVE, the issue will be cleared from the workflow result.

This re-evaluation ensures that your entity’s compliance status is officially updated, reflects the latest risk assessment, and maintains an accurate audit trail.

via API

To trigger a re-evaluation via API, you will execute the workflow again. Refer to the Execute a workflow for the given service profile documentation.

via Portal

The Portal will automatically re-run the workflow for you once all alerts associated with an activity have been resolved (i.e. no alerts with “Needs attention” and “In review” status remain).

Detecting manual overrides

It’s crucial to know if a workflow’s result was changed by a person. When an operator manually changes the status (e.g., from FAIL to PASS), the following fields are populated:

• statusOverrideRequestId: The unique ID of the override request.

• statusOverrideBy: The user who performed the override.

• statusOverrideAt: The timestamp of the override.

To detect an override, check if statusOverrideRequestId exists and is not empty.

5: (Optional) Retrieve all activities

Fetch historical information about the transactions to help get context of the user behavior and investigate.

curl -X 'GET' \  
  'localhost:8103/v2/individuals/d2859e0c-1f63-4208-947a-038bcb7b1e5e/activities?sortField=ACTIVITY_AT&sort=ASC&limit=20&page=1' \                           
  -H 'accept: application/json' \
  -H 'api_key: X ' \ 
  -H 'X-Frankie-CustomerID: ae6f0c56-ddba-4be6-9137-0861b68f52c3' \
  -H 'X-Frankie-Username: fred.flintstone@frankieone.com'

Error handling

The FrankieOne API uses a standardized error format to ensure that you can reliably handle issues that arise from bad requests, server problems, or invalid data. All non-2xx responses will return a consistent JSON error object.

Please refer to the general API Error Codes documentation for a comprehensive list of error types and their meanings. This document replaces any specific error handling guides for individual products unless explicitly stated otherwise.

Scenarios

{
  "details": [
    {
      "issue": "request body has an error: doesn't match schema #/components/schemas/...",
      "issueLocation": "Request",
      "issueType": "Bad Request"
    }
  ],
  "errorCode": "400",
  "errorMsg": "Bad Request",
  "requestId": "01K8SQNX22ZC66XKHMQ1324RJC"
}

{
    "errorCode": "VAL-0400",
    "errorMsg": "Validation failed",
    "details": [
        {
            "issue": "{message}",
            "issueLocation": "{location}"
        }
    ],
    "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}

{
  "details": [
    {
      "issue": "request body has an error: doesn't match schema #/components/schemas/Evaluate-Activity-Req: Error at \"/activity/detail\": input does not contain the discriminator property \"activityType\"\nSchema:\n  {\n    \"description\": \"Details of the activity being checked\",\n    \"discriminator\": {\n      \"mapping\": {\n        \"EVENT\": \"#/components/schemas/Activity-Event\",\n        \"TRANSACTION\": \"#/components/schemas/Activity-Transaction\"\n      },\n      \"propertyName\": \"activityType\"\n    },\n    \"oneOf\": [\n      {\n        \"$ref\": \"#/components/schemas/Activity-Event\"\n      },\n      {\n        \"$ref\": \"#/components/schemas/Activity-Transaction\"\n      }\n    ],\n    \"type\": \"object\"\n  }\n\nValue:\n  null\n",
      "issueLocation": "Request",
      "issueType": "Bad Request"
    }
  ],
  "errorCode": "400",
  "errorMsg": "Bad Request",
  "requestId": "01K8SQNX22ZC66XKHMQ1324RJC"
}

{
    "errorCode": "VAL-0404",
    "errorMsg": "Entity not found",
    "details": [
        {
            "issue": "The specified entity does not exist",
            "issueLocation": "body.party.entityId"
        }
    ],
    "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}

{
  "errorCode": "VAL-0409",
  "errorMsg": "Validation failed",
  "details": [
    {
      "issue": "The transaction with the provided identifier already exists.",
      "issueLocation": "activity.detail.transaction.transactionIdentifier" 
    }
  ],
  "requestId": "01HN9XHZN6MGXM9JXG50K59Q88"
}

{
    "errorCode": "SYS-0500",
    "errorMsg": "Provider service error",
    "details": [
        {
            "issue": "Failed to evaluate activity",
            "issueLocation": "connector"
        }
    ],
    "requestId": "01GVEDZ0C1Q9NWQ699DBBKPE4Y"
}