Implementation Guide - Transaction and Activity monitoring

Prerequisites

Integration overview

Check out the integration page for an overview of the implementation process.

Workflow configured for transaction and activity monitoring

Confirm your workflow setup

Before you can start verifying customers, your account needs to be configured with at least one workflow and one service profile. Your Customer Success Manager typically sets these up for you.You can confirm your setup by calling the GET /v2/workflows endpoint. This will list all the executable monitoring workflows available to you. For Transaction and Activity Monitoring, it is critical to have only one workflow with a lifecyclePhase: MONITORING and monitoringTypes: [“ACTIVITY”]

Request - Get workflows

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}}'

You should receive a 200 OK response with a workflows array. If the array is empty, please contact your Customer Success Manager to get your workflows published.

Response - Get workflows

{
  "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.

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

Evaluate activity request

curl --location 'https://api.uat.frankie.one:443/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

Customer sends transaction / activity data to FrankieOne.
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
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
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.

Get workflow execution result request

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

Issue Type	Description
ACTIVITY_AML	An issue identified during an Anti-Money Laundering (AML) check within the activity monitoring workflow. This could be due to potentially high-risk financial behavior patterns detected during transaction or activity monitoring.
ACTIVITY_FRAUD	An issue identified as potential fraud during the transaction and activity monitoring workflow. This can stem from indicators of fraudulent intent related to financial activities.
ACTIVITY_EVENT	An issue identified as potential fraud during the activity monitoring workflow. This can stem from indicators that are non-transactional or behavioral by nature such as device anomalies, or unusual login patterns or interactions with the device.

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

stepName

API stepName: The name of the specific step that was executed

ACTIVITY_AML - a step dedicated to performing AML checks on the activity.
ACTIVITY_FRAUD - a step dedicated to performing fraud checks on the activity.

Portal

stepName: ACTIVITY_AML is available

stepName: ACTIVITY_FRAUD is available

result

API result: The outcome of this specific step. For monitoring, this can be:

CLEAR (step passed): The step completed successfully without identifying any issues.
HIT (step identified an issue): The step identified a potential issue or match according to its configured rules.
ERROR (technical issue with the step): The step encountered an unrecoverable technical error during its execution. Portal HIT, Expanded view

CLEAR, Expanded view

HIT Expanded view

summary

API summary: A concise, human-readable summary of the step’s outcome.

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

PortalNot displayed in Portal

risk

API risk: The risk assessment specific to this step, including the score it contributed to the overall workflowRiskScore and workflowRiskLevel.

Portal

Activity alerts

On evaluations each activity will have activity results but only activity results that are considered “alerting” will represented as Process Result Objects (PROs) that are treated as alerts and considered needs action.

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' \
  'https://api.uat.frankie.one:443/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.

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

Get Activities request

curl -X 'GET' \  
  'https://api.uat.frankie.one:443/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

Generic Bad request

HTTP Status Code : Frankie Error Code400 : VAL-0400

{
  "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"
}

Bad request - Validation issues (Any business or process validation)

HTTP Status Code : Frankie Error Code400 : VAL-0400

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

Bad request - Schema issues

Invalid limit or page parameter
beforeActivityAt is earlier than afterActivityAt
Invalid sortField other than activityAt
afterActivityAt is in the future

HTTP Status Code : Frankie Error Code400 : VAL-0400

{
  "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"
}

Bad request - Entity not found

HTTP Status Code : Frankie Error Code400 : VAL-0404

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

Duplicated transactions

HTTP Status Code : Frankie Error Code409 : VAL-0409

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

System errors

HTTP Status Code : Frankie Error Code500 : SYS-500

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

Getting Started

Fraud

Transaction Monitoring

Implementation Guide - Transaction and Activity monitoring

Prerequisites

Request - Get workflows

Response - Get workflows

Next Steps

Getting started with Transaction and Activity Monitoring

1: Use the Transaction and Activity Monitoring API

High-level process flow

The `session` object

The `party` object

The `details` object

2: Review alerts

via API

via Portal

Interpreting the results

Overall outcome (`workflowResult` top-level fields)

Issues

Workflow step results

Portal

Activity alerts

3: Resolve alerts

via API

via Portal

4: Re-evaluate the results

via API

via Portal

Detecting manual overrides

5: (Optional) Retrieve all activities

Error handling

Scenarios

Getting Started

Fraud

Transaction Monitoring

​Prerequisites

​Request - Get workflows

​Response - Get workflows

​Next Steps

​Getting started with Transaction and Activity Monitoring

​1: Use the Transaction and Activity Monitoring API

​High-level process flow

​The session object

​The party object

​The details object

​2: Review alerts

via API

via Portal

​Interpreting the results

Overall outcome (workflowResult top-level fields)

​Issues

​Workflow step results

​Portal

​Activity alerts

​3: Resolve alerts

​via API

​via Portal

​4: Re-evaluate the results

​via API

​via Portal

​Detecting manual overrides

​5: (Optional) Retrieve all activities

​Error handling

​Scenarios

Prerequisites

Request - Get workflows

Response - Get workflows

Next Steps

Getting started with Transaction and Activity Monitoring

1: Use the Transaction and Activity Monitoring API

High-level process flow

The `session` object

The `party` object

The `details` object

2: Review alerts

Interpreting the results

Overall outcome (`workflowResult` top-level fields)

Issues

Workflow step results

Portal

Activity alerts

3: Resolve alerts

via API

via Portal

4: Re-evaluate the results

via API

via Portal

Detecting manual overrides

5: (Optional) Retrieve all activities

Error handling

Scenarios