> ## Documentation Index > Fetch the complete documentation index at: https://doc.youverify.co/llms.txt > Use this file to discover all available pages before exploring further. # Send an Event > One entry point for every event type: `onboarding`, `transaction` and `account_activity` (login, card). Triggering events start evaluations; the rest are accepted and stored. The request payloads documented here are for Transaction Monitoring (TM) events only (`transaction` and `account_activity`). 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 platform's id) or their own `externalEntityId` (your id) with a `name` and `accountNumber`; an `account_activity` event does the same at the root of `data`; an `onboarding` event carries `data.externalEntityId` (required) and `data.entityId` (when the workflow is for an existing entity). `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 so the event is processed and enriched faster. **Routing.** `onboarding` (CO) is routed by `workflowId` and `workflowVersion`. `transaction` and `account_activity` (TM) carry an `eventCategory`; a login carries `data.loginMethod`, and a card event carries `data.cardAction` (`created` or `updated`). **Triggering statuses.** Only these start evaluations: transaction `acknowledged`, `pending`; login `attempted`; card `requested`, `activated`, `pin_changed`; and `processing` for any kind. Every other status (for example `completed`, `successful`, `failed`, `issued`, `frozen`, `processed`) is stored without a run. **Which workflows run.** Every event runs the live TM workflows tagged with its `eventCategory` whose `eventTypes` includes its type (a TM workflow must list at least one to be saved or published). An `account_activity` event runs on `{ account_activity: data }`. `eventTypes` decides which events start a workflow, not what it can read: any TM workflow can use the `behavioural_insights.*` variables, including those learned from account activity. **Validation and idempotency.** `data` is validated per `eventType`. A transaction's `transactionReference` is its idempotency key: a repeat of one already evaluated returns the original evaluations with `replayed: true` and runs nothing (its payload is ignored even if it differs); one with no live evaluation yet runs as normal. **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. ## OpenAPI ````yaml /api-reference/specs/cowork.json post /v2/workflows/events openapi: 3.0.3 info: title: Youverify Cowork API version: 2.0.0 description: >- Entity, Activity, Signal, Case and Workflow Management endpoints — the core Cowork platform object model. Assembled from doc.youverify.co/api-reference-sdk, endpoints kept in the exact order they appear in the GitBook navigation. Account-wide error responses (401, 429, 500 on every endpoint; 402 on paid verification calls; 404 on lookup-by-ID calls) are sourced verbatim from Youverify's own "Youverify OS Error Codes" and "Response Codes" pages (doc.youverify.co/youverify-os-error-codes, /get-started/response-codes) and attached via components.responses, since those pages document them account-wide rather than per endpoint. Any error example that a specific endpoint's own page actually showed is kept exactly as documented there instead of being replaced by these. contact: name: Youverify Support email: support@youverify.co servers: - url: https://api.youverify.co description: Production (live, billed) - url: https://api.sandbox.youverify.co description: Sandbox (test data, not billed) security: - ApiKeyAuth: [] tags: - name: Entity Management description: >- Create, retrieve and verify entities (individuals or businesses) — the core object every check attaches to. - name: Activity Management description: Inspect the verification activities run against your account. - name: Signal Management description: Retrieve monitoring signals and their events, by entity or business. - name: Case Management description: Create and manage compliance cases, including AI-generated case summaries. - name: Workflow Management description: >- Send events to Transaction Monitoring and Customer Onboarding workflows, and read the workflows and evaluations (runs) for your business. paths: /v2/workflows/events: post: tags: - Workflow Management summary: Send an Event description: >- One entry point for every event type: `onboarding`, `transaction` and `account_activity` (login, card). Triggering events start evaluations; the rest are accepted and stored. The request payloads documented here are for Transaction Monitoring (TM) events only (`transaction` and `account_activity`). 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 platform's id) or their own `externalEntityId` (your id) with a `name` and `accountNumber`; an `account_activity` event does the same at the root of `data`; an `onboarding` event carries `data.externalEntityId` (required) and `data.entityId` (when the workflow is for an existing entity). `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 so the event is processed and enriched faster. **Routing.** `onboarding` (CO) is routed by `workflowId` and `workflowVersion`. `transaction` and `account_activity` (TM) carry an `eventCategory`; a login carries `data.loginMethod`, and a card event carries `data.cardAction` (`created` or `updated`). **Triggering statuses.** Only these start evaluations: transaction `acknowledged`, `pending`; login `attempted`; card `requested`, `activated`, `pin_changed`; and `processing` for any kind. Every other status (for example `completed`, `successful`, `failed`, `issued`, `frozen`, `processed`) is stored without a run. **Which workflows run.** Every event runs the live TM workflows tagged with its `eventCategory` whose `eventTypes` includes its type (a TM workflow must list at least one to be saved or published). An `account_activity` event runs on `{ account_activity: data }`. `eventTypes` decides which events start a workflow, not what it can read: any TM workflow can use the `behavioural_insights.*` variables, including those learned from account activity. **Validation and idempotency.** `data` is validated per `eventType`. A transaction's `transactionReference` is its idempotency key: a repeat of one already evaluated returns the original evaluations with `replayed: true` and runs nothing (its payload is ignored even if it differs); one with no live evaluation yet runs as normal. **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. operationId: sendWorkflowEvent parameters: - name: token in: header required: true schema: type: string description: API secret token requestBody: required: true content: application/json: schema: type: object required: - eventType - eventStatus - data properties: eventType: type: string description: Type of event. enum: - transaction - account_activity - onboarding schemaVersion: type: string description: Version of the event schema. example: '1.2' externalEventId: type: string description: Your own identifier for the event. eventStatus: type: string description: >- Status of the event. Only triggering statuses start evaluations; others are stored without a run. enum: - acknowledged - pending - completed - attempted - successful - requested - issued - activated - frozen - suspended - unfrozen - pin_changed - closed - canceled - failed lifecycleId: type: string description: >- Optional id that connects related events. We never generate it; events without one are connected to no other event. metadata: type: object description: Free-form metadata about the event. properties: source: type: string description: Where the event came from. example: mobile-app eventCategory: type: string description: >- Category used to select the live TM workflows to run (for `transaction` and `account_activity` events). example: finance data: type: object description: >- Event payload, validated per `eventType`. Fields below are for a `transaction` event. properties: paymentType: type: object properties: direction: type: string enum: - INBOUND - OUTBOUND example: OUTBOUND financials: type: object properties: totalAmount: type: number currency: type: string description: Currency code. parties: type: object properties: sender: $ref: '#/components/schemas/WorkflowEventParty' beneficiaries: type: array items: $ref: '#/components/schemas/WorkflowEventParty' status: type: string description: Transaction status. settled_at: type: string description: Settlement time. format: date-time processed_at: type: string description: Processing time. format: date-time fee_amount: type: number process_method: type: string is_approved: type: boolean is_reversal: type: boolean is_international_override: type: boolean is_triggered_by_user: type: boolean is_round_amount: type: boolean is_large_transaction: type: boolean counterparty: type: object properties: industry: type: object properties: code: type: string is_linked_account: type: boolean is_new: type: boolean age_days: type: number risk_tier: type: string is_watchlisted: type: boolean device: type: object properties: is_proxy: type: boolean crypto: type: object properties: asset_type: type: string wallet_address: type: string travel_rule_complete: type: boolean mixer_exposure: type: boolean sanctioned_address_exposure: type: boolean transactionReference: type: string description: Idempotency key for the transaction. example: eventType: transaction schemaVersion: '1.2' externalEventId: string eventStatus: acknowledged lifecycleId: string metadata: source: mobile-app eventCategory: finance data: paymentType: direction: OUTBOUND financials: totalAmount: 0 currency: string parties: sender: entityId: string entityType: INDIVIDUAL externalEntityId: string name: string accountNumber: string account: balance: 0 riskRating: string accountAge: 0 expectedMonthlyVolume: 0 accountStatus: string beneficialOwnerRiskTier: string productLimit: 0 internalBlacklistFlag: true beneficiaries: - entityId: string entityType: INDIVIDUAL externalEntityId: string name: string accountNumber: string account: balance: 0 riskRating: string accountAge: 0 expectedMonthlyVolume: 0 accountStatus: string beneficialOwnerRiskTier: string productLimit: 0 internalBlacklistFlag: true status: string settled_at: '2026-11-03T21:16:01.593Z' processed_at: '2026-11-03T21:16:01.593Z' fee_amount: 0 process_method: string is_approved: true is_reversal: true is_international_override: true is_triggered_by_user: true is_round_amount: true is_large_transaction: true counterparty: industry: code: string is_linked_account: true is_new: true age_days: 0 risk_tier: string is_watchlisted: true device: is_proxy: true crypto: asset_type: string wallet_address: string travel_rule_complete: true mixer_exposure: true sanctioned_address_exposure: true transactionReference: string responses: '202': description: Event accepted content: application/json: schema: type: object properties: success: type: boolean statusCode: type: integer message: type: string data: type: object properties: evaluations: type: array items: type: object properties: id: type: string description: Evaluation id. status: type: string enum: - PENDING - RUNNING - PAUSED - SUCCESS - FAILED decision: type: string enum: - BLOCK - FREEZE - HOLD - REVIEW - ALERT - ALLOW decisionReason: type: string decisionFinal: type: boolean description: Whether the decision is final. riskScore: type: number actionsApplied: type: array items: type: string outcome: type: object properties: result: type: string example: approved flagged: type: array items: type: string entityId: type: string entityName: type: string count: type: integer description: Number of evaluations started. replayed: type: boolean description: >- `true` when the `transactionReference` was already evaluated; the original evaluations are returned and nothing runs. links: type: array items: type: object example: success: true statusCode: 202 message: Event accepted data: evaluations: - id: string status: PENDING decision: BLOCK decisionReason: string decisionFinal: true riskScore: 0 actionsApplied: - string outcome: result: approved flagged: - string entityId: string entityName: string count: 0 replayed: true links: - {} '401': $ref: '#/components/responses/Error401Unauthorized' '429': $ref: '#/components/responses/Error429TooManyRequests' '500': $ref: '#/components/responses/Error500ServerError' components: schemas: WorkflowEventParty: type: object description: >- A party to the transaction (the sender or a beneficiary). Identify it with `entityId` (Youverify's id, faster) or `externalEntityId` (your id). required: - entityType properties: entityId: type: string description: >- Youverify entity id. Send it whenever you have it: we then skip resolving the entity from your `externalEntityId`, so the event is processed and enriched faster. entityType: type: string description: Type of entity. enum: - INDIVIDUAL - BUSINESS externalEntityId: type: string description: Your own identifier for the entity. name: type: string description: Name of the party. accountNumber: type: string description: Account number of the party. account: type: object properties: balance: type: number description: Account balance. riskRating: type: string description: Risk rating you hold for the party. accountAge: type: number description: Age of the account. expectedMonthlyVolume: type: number description: Expected monthly volume for the account. accountStatus: type: string description: Status of the account. beneficialOwnerRiskTier: type: string description: Risk tier of the beneficial owner. productLimit: type: number description: Limit on the product used. internalBlacklistFlag: type: boolean description: Whether the party is on your internal blacklist. responses: Error401Unauthorized: description: Unauthorized — the token header is missing or invalid. content: application/json: example: success: false statusCode: 401 message: Permission denied name: UnauthorizedError data: {} Error429TooManyRequests: description: Too Many Requests — you have exceeded the rate limit; wait and retry. content: application/json: example: success: false statusCode: 429 message: Too many requests name: RateLimitError data: {} Error500ServerError: description: >- Internal Server Error — a rare, unexpected failure on Youverify's side. Contact support@youverify.co if it persists. content: application/json: example: success: false statusCode: 500 message: Internal Server Error name: Error data: {} securitySchemes: ApiKeyAuth: type: apiKey in: header name: token description: Your Youverify API secret key. Never expose client-side. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.