Skip to main content

​
Use the Transaction and Activity Monitoring API

Start sending transaction and activity details to FrankieOne by calling Evaluate an activity endpoint 
curl --location 'https://api.uat.frankie.one:443/v2/activities' \
--header 'X-Frankie-CustomerID: {{your_customer_id}}' \
--header 'api_key: {{your_api_key}}' \
--header 'Content-Type: application/json' \
--data '{
    "activity": {
        "session": {
            "token": "'"$TOKEN"'"
        },
        "party": {
            "entityId": "'"{{entityId}}"'",
            "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": "{{hashedPan}}",
                    "maskedPan": "******321",
                    "name": "super saver",
                    "class": "PERSONAL",
                    "externalIdentifier": "{{externalIdentifier}}",
                    "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": "{{hashedPan}}",
                    "maskedPan": "******133",
                    "name": "Property Sales Account",
                    "class": "BUSINESS"
                }
            }
        }
    }
}'

​
High-level process flow

Activity Evaluation Flow Diagram
  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. Passing an existing session token from your system will make sure FrankieOne’s activity linking aligns cleanly with your own session model, including longer‑running sessions.

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

​
Overriding party details for an activity

When you evaluate an activity, you can pass party details — such as address, phone number, or email address — directly in the request payload. These values override the data stored on the entity for the purposes of that evaluation only. The entity’s stored data is not modified. This is useful when the activity involves data that is not yet recorded on the entity, or when the data at the time of the activity differs from the entity’s current state. Additional details like addresses, emailAddresses, and phoneNumbershelp to give context to the party’s profile for more accurate risk assessment. Below are the supported override fields in the party object:
FieldDescription
addressesOne or more address objects. Reference an existing address by addressId, or provide a new address without an ID.
phoneNumbersOne or more phone number objects.
emailAddressesOne or more email address objects.
nameThe individual’s name. Overrides the entity’s stored primary name for this evaluation.
dateOfBirthThe individual’s date of birth.
registeredNameThe organization’s registered name (organization entities only).
The override data are stored by FrankieOne as a snapshot of the party details provided at evaluation time alongside the activity record. This means:
  • The party details returned by Get Activity and Get Activities reflect the data that was present at the time of evaluation, not the current state of the entity.
  • If the entity’s data changes after an activity is evaluated, the activity record retains the snapshot as it was at evaluation time.
  • Party details are stored as encrypted data within the activity record.

​
The details object

Contains specific information about the activity being evaluated.
  • activityType : Categorizes the activity broadly (for example, TRANSACTION or EVENT).
  • transactionIdentifier - This field in the payload is only present on TRANSACTION activityTypes. Each evaluation requires this to be unique.
  • eventType : Provides a more granular classification of the activity (such as LOGIN, WITHDRAWAL, DEPOSIT, or 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.
    • customAttributes.partyAccount is an optional string that identifies which account the activity relates to.
      • Look for a matching individual.externalReference entry where type = "ACCOUNT" and the value equals partyAccount.
      • If exactly one match is found, FrankieOne enriches the evaluation with that account’s metadata, using keys prefixed with partyAccount (for example, partyAccountStatus, partyAccountProductType).
      • If no matching individual.externalReference entry is found, no enrichment is applied and the evaluation continues normally.
      • If more than one ACCOUNT match is found, the evaluation returns an error.
      • Note: Existing custom attributes are never overwritten by enrichment.
  • externalReference: Allows you to add any other identifiers for the individual or organization from your own system or a third-party system. Some external references are forwarded to the provider for enrichment. These are:
    • "type": "CUSTOMER","name": "CUSTOMER-REFERENCE" - This is an optional external reference. This is treated as an identifier from your own system.
      • When type: CUSTOMER and name: CUSTOMER-REFERENCE are included in the externalReference array of the activity payload, FrankieOne uses that value during evaluation.
      • If not included in the activity payload, FrankieOne falls back to the matching external reference stored on the individual or organization entity (where type = CUSTOMER and name = CUSTOMER-REFERENCE).

​
Setting a custom transaction display name

You can set an optional transactionLabel on a transaction to give it a meaningful display name. By default, the display name is inferred from currencyType and transactionType (for example, FIAT WITHDRAWAL). When a label is provided, it replaces this default in the FrankieOne Portal and in downstream fraud analysis.
FieldTypeRequiredMax length
transactionLabelstringNo128 characters
Note: This does not affect which fraud checks are run. Check selection continues to be determined by currencyType and transactionType. These objects are further detailed in the API documentation.

​
Next step

Once you have submitted your activity evaluation request, read the response to understand what FrankieOne found. Interpret activity results →