Workflow Events Management

Send an Event

One entry point for every event type. Send an event when something happens that your workflows should see, such as a payment, a login or a card action. Triggering events start evaluations; every other event is accepted and stored.

Event types

Pick the request variant that matches eventType. Every field in the schema lists its type, whether it is required and what it means. Use the Examples selector to see a complete payload for each variant.

Event	`eventType`	What it describes	Workflow type
Transaction	`transaction`	A payment, with its sender and beneficiaries in `data`.	Transaction Monitoring (TM)
Login	`account_activity`	A customer login. Carries `data.loginMethod`.	Transaction Monitoring (TM)
Card	`account_activity`	A card event. Carries `data.cardAction` (`created` or `updated`).	Transaction Monitoring (TM)
Onboarding	`onboarding`	A customer onboarding event. Carries `data.externalEntityId` (required) and `data.entityId` when the workflow is for an existing entity.	Customer Onboarding (CO)

A login and a card event are both account_activity. Never send loginMethod and cardAction together. Pick the matching request variant below. The fields inside an onboarding event’s data beyond the entity fields depend on the workflow you are running.

Routing

transaction and account_activity events carry an eventCategory. Every event runs the live TM workflows tagged with that category whose eventTypes includes the event’s type. A TM workflow must list at least one event type to be saved or published.
onboarding events are routed by workflowId and workflowVersion.
eventTypes decides which events start a workflow, not what the workflow can read. Any TM workflow can use the behavioural_insights.* variables, including those learned from account activity.
An account_activity event runs on { account_activity: data }.

Which statuses start an evaluation

Event	Triggering `eventStatus`
Transaction	`acknowledged`, `pending`
Login	`attempted`
Card	`requested`, `activated`, `pin_changed`
Any kind	`processing`

Any other status (for example completed, successful, failed, issued, frozen, processed) is stored without a run, and still updates the aggregates. Which statuses are allowed depends on the kind of event.

Identifying the entity

There is no externalEntityId on the event itself. Each entity identifies itself inside data:

On a transaction, the sender and each beneficiary carry their own entityId (the Youverify id) or their own externalEntityId (your id), with a name and accountNumber.
On an account_activity event, the same fields sit at the root of data.
entityType (INDIVIDUAL or BUSINESS) is required inside data: at the root of data for account_activity and onboarding events, and on the sender and each beneficiary of a transaction.

Send the entityId whenever you have it. We then skip resolving the entity from your externalEntityId, so the event is processed and enriched faster.

Idempotency

externalEventId is the idempotency key. Sending the same externalEventId again returns the original evaluations with replayed: true and runs nothing. The repeat’s payload is ignored even if it differs. An externalEventId with no live evaluation yet runs as normal. A transaction’s transactionReference identifies the transaction, not the event.

Lifecycle

An event has a lifecycleId only if you send one; we never generate it. An event without one is connected to no other event and adds nothing to session-risk counters. Send the same lifecycleId on related events, such as one session or one payment.

POST

workflows

events

curl --request POST \
  --url https://api.youverify.co/v2/workflows/events \
  --header 'Content-Type: application/json' \
  --header 'token: <api-key>' \
  --data '
{
  "eventType": "transaction",
  "schemaVersion": "1.2",
  "eventCategory": "finance",
  "eventStatus": "acknowledged",
  "externalEventId": "EVT-20261030-0001",
  "lifecycleId": "LC-5521-session-88",
  "metadata": {
    "source": "mobile-app",
    "appVersion": "4.12.0"
  },
  "data": {
    "transactionReference": "TXN-20261030-0001",
    "creationDateTime": "2026-10-30T10:04:12.000Z",
    "paymentType": {
      "channel": "TRANSFER",
      "rail": "NIP",
      "direction": "OUTBOUND",
      "instrument": "CREDIT_TRANSFER",
      "clearingSystem": "NIBSS",
      "localInstrument": "NIP-INSTANT",
      "categoryPurpose": "SUPP"
    },
    "financials": {
      "totalAmount": "4950000.00",
      "currency": "NGN",
      "totalBaseAmount": "3300.00",
      "baseCurrency": "USD",
      "exchangeRate": "1500.00",
      "rateSource": "CBN",
      "rateTimestamp": "2026-10-30T10:00:00.000Z",
      "chargeBearer": "SHAR"
    },
    "parties": {
      "sender": {
        "entityId": "6ae459c0b99fb556a487f12f",
        "externalEntityId": "cust-1042",
        "entityType": "INDIVIDUAL",
        "name": "Chinedu Okafor",
        "accountNumber": "0123456789",
        "nationality": "NG",
        "countryOfResidence": "NG",
        "dateOfBirth": "1988-04-17",
        "placeOfBirth": {
          "city": "Enugu",
          "country": "NG"
        },
        "address": {
          "streetName": "Adeola Odeku Street",
          "buildingNumber": "12",
          "townName": "Victoria Island",
          "countrySubdivision": "Lagos",
          "postCode": "101241",
          "country": "NG"
        },
        "identification": [
          {
            "scheme": "BVN",
            "id": "22123456789",
            "issuerCountry": "NG"
          }
        ],
        "account": {
          "id": "0123456789",
          "scheme": "NUBAN",
          "currency": "NGN",
          "type": "CURRENT",
          "name": "Chinedu Okafor",
          "balance": "9800000.00"
        },
        "bank": {
          "name": "Example Bank Plc",
          "countryCode": "NG",
          "bic": "EXBKNGLA"
        },
        "contact": {
          "email": "chinedu@example.com",
          "phone": "+2348012345678"
        },
        "riskRating": "medium",
        "accountAge": 420,
        "accountAgeUnit": "days",
        "expectedMonthlyVolume": 3000000,
        "accountStatus": "active",
        "productLimit": 10000000,
        "internalBlacklistFlag": false
      },
      "beneficiaries": [
        {
          "externalEntityId": "ben-7731",
          "entityType": "BUSINESS",
          "name": "Adeyemi Trading Ltd",
          "accountNumber": "2012345678",
          "address": {
            "townName": "Accra",
            "country": "GH"
          },
          "account": {
            "id": "2012345678",
            "scheme": "BBAN",
            "currency": "GHS"
          },
          "bank": {
            "name": "Example Ghana Bank",
            "countryCode": "GH",
            "bic": "EXGHGHAC"
          },
          "transferDetails": {
            "paymentItemId": "1",
            "endToEndId": "E2E-20261030-0001",
            "amount": "4950000.00",
            "currency": "NGN",
            "creditAmount": "49500.00",
            "creditCurrency": "GHS",
            "purposeCode": "SUPP",
            "remittanceInfo": "Invoice INV-2209"
          }
        }
      ]
    },
    "device": {
      "ipAddress": "102.89.1.55",
      "geoCountry": "NG",
      "sessionId": "sess-88",
      "deviceFingerprint": "dfp-3f9a2c",
      "userAgent": "ExampleApp/4.12.0 (iOS 18.1)",
      "channelApp": "MOBILE_APP",
      "geo": {
        "lat": 6.4281,
        "lon": 3.4219,
        "accuracyM": 30
      }
    },
    "isInternational": true,
    "isNight": false
  }
}
'

{
  "success": true,
  "statusCode": 202,
  "message": "Event accepted",
  "data": {
    "eventId": "6aeb1d628cae1179877dab7f",
    "eventType": "transaction",
    "eventCategory": "finance",
    "eventStatus": "PROCESSED",
    "externalEventId": "EVT-mvsh54ho-2",
    "evaluations": [
      {
        "id": "6aeb1d628cae1179877dab80",
        "status": "SUCCESS",
        "decision": "REVIEW",
        "decisionReason": "Rule 'High-value outbound transfer' triggered: amount above 1,000,000 NGN",
        "decisionFinal": true,
        "riskScore": 62,
        "actionsApplied": [
          "generate_alert",
          "create_case"
        ],
        "outcome": {
          "result": "manual_review",
          "flagged": [
            "Transfer amount above 1,000,000 NGN"
          ]
        },
        "workflow": {
          "id": "6aeb1d628cae1179877dab01",
          "type": "TM_WORKFLOW",
          "monitoringType": "REALTIME",
          "version": 3
        },
        "timing": {
          "startedAt": "2026-11-04T19:20:00.000Z",
          "executionTimeMs": 45
        },
        "lifecycleState": "PENDING_CASE_RESOLUTION",
        "riskProfile": {
          "score": 62,
          "contributingFactors": [
            {
              "factor": "High-value outbound transfer",
              "score": 62
            }
          ]
        },
        "rulesMatched": [
          {
            "ruleId": "rule_high_value",
            "nodeId": "node_high_value",
            "valueTriggered": 1250000
          }
        ],
        "actions": [
          {
            "actionType": "GENERATE_ALERT",
            "details": null
          },
          {
            "actionType": "CREATE_CASE",
            "details": "Routed to L1_AML_Queue"
          }
        ]
      }
    ],
    "count": 1,
    "replayed": false
  },
  "links": [
    {}
  ]
}

{
  "success": false,
  "statusCode": 401,
  "message": "Permission denied",
  "name": "UnauthorizedError",
  "data": {}
}

{
  "success": false,
  "statusCode": 429,
  "message": "Too many requests",
  "name": "RateLimitError",
  "data": {}
}

{
  "success": false,
  "statusCode": 500,
  "message": "Internal Server Error",
  "name": "Error",
  "data": {}
}

Authorizations

token

string

header

required

Your Youverify API secret key. Never expose client-side.

Headers

token

string

required

API secret token

Body

application/json

Option 1
Option 2
Option 3
Option 4

TM transaction event (routed by eventCategory).

eventType

enum<string>

required

The kind of event: transaction or account_activity (a login or a card event).

Available options:

transaction

Example:

"transaction"

externalEventId

string

required

Your own unique id for this event. It is the idempotency key: sending the same id again returns the original evaluations instead of starting new ones.

Maximum string length: 128

eventStatus

enum<string>

required

Where the event is in its life. Only a triggering status starts a workflow (a transaction: acknowledged, pending; a login: attempted; a card event: requested, activated, pin_changed); any other status is stored and still updates the aggregates. Which statuses are allowed depends on the kind of event.

Available options:

acknowledged,

pending,

completed,

attempted,

successful,

requested,

issued,

activated,

frozen,

suspended,

unfrozen,

pin_changed,

closed,

canceled,

failed,

reversed

Example:

"acknowledged"

eventCategory

enum<string>

required

Routes the event to the workflows tagged with this category, for example finance or kyc.

Available options:

finance,

kyc,

travel_rule,

user_event,

gambling,

audit_trail_event,

crypto,

insurance,

investment

data

object

required

The transaction: its payment type, amounts, parties and the flags you decide (isInternational, isNight).

Show child attributes

schemaVersion

string

Version of this payload schema. Only major version 1 is supported.

Pattern: ^1\.\d+$|^1\.\d+\.\d+$

Example:

"1.2"

lifecycleId

string

Your identifier tying together several events that belong to the same lifecycle, for example one session or one payment.

Maximum string length: 128

metadata

object

Information about the event itself, the same on every event type. Any other key you add is kept and passed on.

Show child attributes

Response

Event accepted. evaluations lists any evaluations the event started.

success

boolean

required

Example:

true

statusCode

enum<integer>

required

Available options:

202

Example:

202

message

enum<string>

required

Available options:

Event accepted

Example:

"Event accepted"

data

object

required

Show child attributes

links

object[]

curl --request POST \
  --url https://api.youverify.co/v2/workflows/events \
  --header 'Content-Type: application/json' \
  --header 'token: <api-key>' \
  --data '
{
  "eventType": "transaction",
  "schemaVersion": "1.2",
  "eventCategory": "finance",
  "eventStatus": "acknowledged",
  "externalEventId": "EVT-20261030-0001",
  "lifecycleId": "LC-5521-session-88",
  "metadata": {
    "source": "mobile-app",
    "appVersion": "4.12.0"
  },
  "data": {
    "transactionReference": "TXN-20261030-0001",
    "creationDateTime": "2026-10-30T10:04:12.000Z",
    "paymentType": {
      "channel": "TRANSFER",
      "rail": "NIP",
      "direction": "OUTBOUND",
      "instrument": "CREDIT_TRANSFER",
      "clearingSystem": "NIBSS",
      "localInstrument": "NIP-INSTANT",
      "categoryPurpose": "SUPP"
    },
    "financials": {
      "totalAmount": "4950000.00",
      "currency": "NGN",
      "totalBaseAmount": "3300.00",
      "baseCurrency": "USD",
      "exchangeRate": "1500.00",
      "rateSource": "CBN",
      "rateTimestamp": "2026-10-30T10:00:00.000Z",
      "chargeBearer": "SHAR"
    },
    "parties": {
      "sender": {
        "entityId": "6ae459c0b99fb556a487f12f",
        "externalEntityId": "cust-1042",
        "entityType": "INDIVIDUAL",
        "name": "Chinedu Okafor",
        "accountNumber": "0123456789",
        "nationality": "NG",
        "countryOfResidence": "NG",
        "dateOfBirth": "1988-04-17",
        "placeOfBirth": {
          "city": "Enugu",
          "country": "NG"
        },
        "address": {
          "streetName": "Adeola Odeku Street",
          "buildingNumber": "12",
          "townName": "Victoria Island",
          "countrySubdivision": "Lagos",
          "postCode": "101241",
          "country": "NG"
        },
        "identification": [
          {
            "scheme": "BVN",
            "id": "22123456789",
            "issuerCountry": "NG"
          }
        ],
        "account": {
          "id": "0123456789",
          "scheme": "NUBAN",
          "currency": "NGN",
          "type": "CURRENT",
          "name": "Chinedu Okafor",
          "balance": "9800000.00"
        },
        "bank": {
          "name": "Example Bank Plc",
          "countryCode": "NG",
          "bic": "EXBKNGLA"
        },
        "contact": {
          "email": "chinedu@example.com",
          "phone": "+2348012345678"
        },
        "riskRating": "medium",
        "accountAge": 420,
        "accountAgeUnit": "days",
        "expectedMonthlyVolume": 3000000,
        "accountStatus": "active",
        "productLimit": 10000000,
        "internalBlacklistFlag": false
      },
      "beneficiaries": [
        {
          "externalEntityId": "ben-7731",
          "entityType": "BUSINESS",
          "name": "Adeyemi Trading Ltd",
          "accountNumber": "2012345678",
          "address": {
            "townName": "Accra",
            "country": "GH"
          },
          "account": {
            "id": "2012345678",
            "scheme": "BBAN",
            "currency": "GHS"
          },
          "bank": {
            "name": "Example Ghana Bank",
            "countryCode": "GH",
            "bic": "EXGHGHAC"
          },
          "transferDetails": {
            "paymentItemId": "1",
            "endToEndId": "E2E-20261030-0001",
            "amount": "4950000.00",
            "currency": "NGN",
            "creditAmount": "49500.00",
            "creditCurrency": "GHS",
            "purposeCode": "SUPP",
            "remittanceInfo": "Invoice INV-2209"
          }
        }
      ]
    },
    "device": {
      "ipAddress": "102.89.1.55",
      "geoCountry": "NG",
      "sessionId": "sess-88",
      "deviceFingerprint": "dfp-3f9a2c",
      "userAgent": "ExampleApp/4.12.0 (iOS 18.1)",
      "channelApp": "MOBILE_APP",
      "geo": {
        "lat": 6.4281,
        "lon": 3.4219,
        "accuracyM": 30
      }
    },
    "isInternational": true,
    "isNight": false
  }
}
'

{
  "success": true,
  "statusCode": 202,
  "message": "Event accepted",
  "data": {
    "eventId": "6aeb1d628cae1179877dab7f",
    "eventType": "transaction",
    "eventCategory": "finance",
    "eventStatus": "PROCESSED",
    "externalEventId": "EVT-mvsh54ho-2",
    "evaluations": [
      {
        "id": "6aeb1d628cae1179877dab80",
        "status": "SUCCESS",
        "decision": "REVIEW",
        "decisionReason": "Rule 'High-value outbound transfer' triggered: amount above 1,000,000 NGN",
        "decisionFinal": true,
        "riskScore": 62,
        "actionsApplied": [
          "generate_alert",
          "create_case"
        ],
        "outcome": {
          "result": "manual_review",
          "flagged": [
            "Transfer amount above 1,000,000 NGN"
          ]
        },
        "workflow": {
          "id": "6aeb1d628cae1179877dab01",
          "type": "TM_WORKFLOW",
          "monitoringType": "REALTIME",
          "version": 3
        },
        "timing": {
          "startedAt": "2026-11-04T19:20:00.000Z",
          "executionTimeMs": 45
        },
        "lifecycleState": "PENDING_CASE_RESOLUTION",
        "riskProfile": {
          "score": 62,
          "contributingFactors": [
            {
              "factor": "High-value outbound transfer",
              "score": 62
            }
          ]
        },
        "rulesMatched": [
          {
            "ruleId": "rule_high_value",
            "nodeId": "node_high_value",
            "valueTriggered": 1250000
          }
        ],
        "actions": [
          {
            "actionType": "GENERATE_ALERT",
            "details": null
          },
          {
            "actionType": "CREATE_CASE",
            "details": "Routed to L1_AML_Queue"
          }
        ]
      }
    ],
    "count": 1,
    "replayed": false
  },
  "links": [
    {}
  ]
}

{
  "success": false,
  "statusCode": 401,
  "message": "Permission denied",
  "name": "UnauthorizedError",
  "data": {}
}

{
  "success": false,
  "statusCode": 429,
  "message": "Too many requests",
  "name": "RateLimitError",
  "data": {}
}

{
  "success": false,
  "statusCode": 500,
  "message": "Internal Server Error",
  "name": "Error",
  "data": {}
}

Cowork API

Quick Check API

SDK API

Send an Event

Event types

Routing

Which statuses start an evaluation

Identifying the entity

Idempotency

Lifecycle

Authorizations

Headers

Body

Response