> ## 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. 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. ## 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 Events 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 Events Management description: >- Send events to your Transaction Monitoring (TM) and Customer Onboarding (CO) workflows, and read the workflows and evaluations (runs) for your business. paths: /v2/workflows/events: post: tags: - Workflow Events Management summary: Send an Event description: > 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. operationId: sendWorkflowEvent parameters: - name: token in: header required: true schema: type: string description: API secret token requestBody: required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/TransactionEvent' - $ref: '#/components/schemas/LoginEvent' - $ref: '#/components/schemas/CardEvent' - $ref: '#/components/schemas/OnboardingEvent' examples: transaction: summary: Transaction description: A NIP transfer from an individual to a business beneficiary. value: 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 login: summary: Login description: A login attempt (account_activity with data.loginMethod). value: eventType: account_activity schemaVersion: '1.2' eventCategory: user_event eventStatus: attempted externalEventId: EVT-LOGIN-20261030-0001 lifecycleId: LC-5521-session-88 data: entityId: 6ae459c0b99fb556a487f12f externalEntityId: cust-1042 entityType: INDIVIDUAL timestamp: '2026-10-30T10:02:30.000Z' externalLoginId: login-90017 externalSessionId: sess-88 username: chinedu.okafor loginMethod: password loginStatus: successful credentialChangeType: password device: registeredDevice: false newDevice: true externalDeviceId: dfp-3f9a2c ipAddressV4: 102.89.1.55 ipAddressLatitude: 6.4281 ipAddressLongitude: 3.4219 ipAddressCity: Lagos ipAddressRegion: Lagos ipAddressCountryCode: NG deviceIsp: MTN Nigeria deviceType: mobile deviceOs: iOS 18.1 screenResolution: 1179x2556 timezoneOffset: '+01:00' browserType: Safari browserVersion: '18.1' browserLanguage: en-NG cookiesEnabled: 'true' javascriptEnabled: 'true' firstSeenAt: '2026-10-30T10:02:30.000Z' metadata: appVersion: 4.12.0 onboarding: summary: Onboarding description: >- A Customer Onboarding event for a business. Fields in `data` beyond the entity fields depend on the workflow (here, a CAC registration number). value: eventType: onboarding externalEventId: EVT-ONB-20261106-0001 eventStatus: pending workflowId: wfw_6aec90ccc34dc00ea4303800 workflowVersion: 1 metadata: {} data: externalEntityId: cust-2087 entityType: BUSINESS cac_rc_number_registrationNumber: RC1234567 card: summary: Card description: A card created event (account_activity with data.cardAction). value: eventType: account_activity schemaVersion: '1.2' eventCategory: user_event eventStatus: requested externalEventId: EVT-CARD-20261030-0001 lifecycleId: LC-5521-session-88 data: entityId: 6ae459c0b99fb556a487f12f externalEntityId: cust-1042 entityType: INDIVIDUAL timestamp: '2026-10-30T10:03:00.000Z' cardAction: created externalCardId: card-55012 cardName: Chinedu O. productName: Platinum Virtual Debit productCode: PLT-VDC cardType: debit formFactor: virtual issuedAt: '2026-10-30T10:03:00.000Z' expiryMonth: '10' expiryYear: '2030' pinUpdatedAt: '2026-10-30T10:03:30.000Z' pinUpdateMethod: app isLocked: false lockExpiresAt: '2026-10-31T10:03:00.000Z' cardStatus: pending_activation statusDetail: Awaiting first use replacesExternalCardId: card-44871 replacementReason: lost channel: mobile-app role: primary accountNumber: '0123456789' currency: NGN metadata: source: mobile-app responses: '202': description: >- Event accepted. `evaluations` lists any evaluations the event started. content: application/json: schema: $ref: '#/components/schemas/SendEventResponse' example: 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: - {} '401': $ref: '#/components/responses/Error401Unauthorized' '429': $ref: '#/components/responses/Error429TooManyRequests' '500': $ref: '#/components/responses/Error500ServerError' components: schemas: TransactionEvent: type: object description: TM transaction event (routed by eventCategory). properties: eventType: type: string description: >- The kind of event: transaction or account_activity (a login or a card event). enum: - transaction example: transaction schemaVersion: type: string description: Version of this payload schema. Only major version 1 is supported. pattern: ^1\.\d+$|^1\.\d+\.\d+$ example: '1.2' externalEventId: type: string description: >- 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. maxLength: 128 eventStatus: type: string description: >- 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. enum: - acknowledged - pending - completed - attempted - successful - requested - issued - activated - frozen - suspended - unfrozen - pin_changed - closed - canceled - failed - reversed example: acknowledged lifecycleId: type: string description: >- Your identifier tying together several events that belong to the same lifecycle, for example one session or one payment. maxLength: 128 metadata: type: object description: >- Information about the event itself, the same on every event type. Any other key you add is kept and passed on. properties: source: type: string description: The system the event came from, for example core-banking. appVersion: type: string description: The version of your app that sent the event. traceId: type: string description: 'A W3C trace id: 32 hex characters.' pattern: ^[0-9a-fA-F]{32}$ testMode: type: boolean description: >- true evaluates and logs the event but never acts on it (no alerts, cases or shadow runs). eventCategory: type: string description: >- Routes the event to the workflows tagged with this category, for example finance or kyc. enum: - finance - kyc - travel_rule - user_event - gambling - audit_trail_event - crypto - insurance - investment data: type: object description: >- The transaction: its payment type, amounts, parties and the flags you decide (isInternational, isNight). properties: paymentType: type: object description: >- How the payment is made: its channel, rail, direction and instrument. properties: direction: type: string description: >- Which way the money moves, relative to your business: OUTBOUND (you send) or INBOUND (you receive). It decides which party is your customer: the sender on OUTBOUND, the beneficiary on INBOUND. enum: - OUTBOUND - INBOUND channel: type: string description: 'The routing key: CARD or TRANSFER.' enum: - CARD - TRANSFER rail: type: string description: >- The payment scheme, for example NIP, RTGS, SWIFT, ACH, INTERNAL, WALLET, VISA, MASTERCARD, VERVE or AMEX. Extensible, so not an enum. instrument: type: string description: >- What kind of business event this is: CREDIT_TRANSFER, AUTHORISATION, REVERSAL, REFUND, CASH_WITHDRAWAL or ADVICE. enum: - CREDIT_TRANSFER - AUTHORISATION - REVERSAL - REFUND - CASH_WITHDRAWAL - ADVICE clearingSystem: type: string description: The clearing or scheme operator (ISO 20022 code). localInstrument: type: string description: >- The scheme-specific product code (ISO 20022 code), for example NIP-INSTANT. categoryPurpose: type: string description: >- The category of purpose for the whole message (ISO 20022 code), for example SUPP, SALA or CASH. required: - direction - channel - rail - instrument financials: type: object description: >- The money in the transaction: the total debited and its currency. properties: totalAmount: oneOf: - type: number - type: string pattern: ^(?:\d+|\d+\.\d+)$ description: >- The total debited from the sender, greater than 0, as a number or a decimal string. It must equal the sum of the beneficiaries' transferDetails.amount. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. currency: type: string description: 'ISO 4217 currency of totalAmount: the debit currency.' maxLength: 3 minLength: 3 totalBaseAmount: oneOf: - type: number - type: string description: >- totalAmount converted to baseCurrency, as a number or a decimal string. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. baseCurrency: type: string description: >- ISO 4217 house base currency used by threshold rules, typically USD. maxLength: 3 minLength: 3 exchangeRate: oneOf: - type: number - type: string description: How many units of baseCurrency one unit of currency buys. rateSource: type: string description: Where the exchange rate came from, for example CBN. rateTimestamp: type: string description: When the exchange rate was captured (ISO 8601). chargeBearer: type: string description: >- Who pays the charges: DEBT (the sender), CRED (the beneficiary), SHAR (shared) or SLEV (service level). enum: - DEBT - CRED - SHAR - SLEV required: - totalAmount - currency parties: type: object description: Who sends the money and who receives it. properties: sender: type: object description: The party that is debited. properties: entityId: type: string description: >- Our id for the party. Send it whenever you have it: it skips the lookup. maxLength: 128 entityType: type: string description: 'What the party is: INDIVIDUAL or BUSINESS.' enum: - INDIVIDUAL - BUSINESS externalEntityId: type: string description: >- Your own id for the party. Required when entityId is not sent. maxLength: 128 name: type: string description: >- The party's full legal name (up to 140 characters). Required when entityId is not sent. maxLength: 140 accountNumber: type: string description: >- The party's account number. Used to find or create the party when entityId is not sent, which is when it is required. nationality: type: string description: >- ISO 3166-1 alpha-2 nationality; for a business, its country of incorporation. maxLength: 2 minLength: 2 countryOfResidence: type: string description: ISO 3166-1 alpha-2 country the party lives in. maxLength: 2 minLength: 2 dateOfBirth: type: string description: Date of birth, YYYY-MM-DD (individuals only). pattern: ^\d{4}-\d{2}-\d{2}$ placeOfBirth: type: object description: Where the party was born (individuals only). properties: city: type: string description: City of birth. country: type: string description: ISO 3166-1 alpha-2 country of birth. maxLength: 2 minLength: 2 address: type: object description: The party's postal address. properties: country: type: string description: >- ISO 3166-1 alpha-2 country code. Required whenever an address is sent. maxLength: 2 minLength: 2 streetName: type: string description: Street name (up to 70 characters). maxLength: 70 buildingNumber: type: string description: Building number (up to 16 characters). maxLength: 16 buildingName: type: string description: Building name (up to 35 characters). maxLength: 35 floor: type: string description: Floor or level (up to 70 characters). maxLength: 70 postCode: type: string description: Postal or ZIP code (up to 16 characters). maxLength: 16 townName: type: string description: City or town (up to 35 characters). maxLength: 35 districtName: type: string description: District or neighbourhood (up to 35 characters). maxLength: 35 countrySubdivision: type: string description: >- State, province or region, for example LA for Lagos (up to 35 characters). maxLength: 35 department: type: string description: Department (up to 70 characters). maxLength: 70 subDepartment: type: string description: Sub-department (up to 70 characters). maxLength: 70 addressLines: type: array description: >- Up to 7 free-text address lines of up to 70 characters each. Use only when you cannot send the structured fields above. string maxLength: 70] items: {} maxItems: 7 required: - country identification: type: array description: Government or organisation identifiers for the party. { items: type: object description: One government or organisation identifier. properties: scheme: type: string description: >- The kind of identifier, for example BVN, NIN or PASSPORT. id: type: string description: The identifier itself. issuerCountry: type: string description: ISO 3166-1 alpha-2 country that issued it. maxLength: 2 minLength: 2 issueDate: type: string description: When it was issued, YYYY-MM-DD. pattern: ^\d{4}-\d{2}-\d{2}$ expiryDate: type: string description: When it expires, YYYY-MM-DD. pattern: ^\d{4}-\d{2}-\d{2}$ ultimateParty: type: object description: >- The real originator or beneficiary, where different from this party. It is screened. contact: type: object description: How to reach the party. Used for link analysis only. properties: email: type: string description: The party's email address. format: email phone: type: string description: >- The party's phone number, for example +2348012345678. riskRating: type: string description: >- Your own risk rating for the party, for example low, medium or high. Used as the customer's risk rating when we have none (variable Risk Rating). accountAge: type: number description: >- How long the account has been open, in the unit you give in accountAgeUnit. Send the two together. The Account Age variable holds whole years, so it is worked out as days ÷ 365, weeks ÷ 52 or months ÷ 12, rounded down. format: float accountAgeUnit: type: string description: >- The unit accountAge is stated in: days, weeks, months or years. You choose it; send it with accountAge. enum: - days - weeks - months - years expectedMonthlyVolume: type: number description: >- The transaction volume expected each month, declared or assigned at onboarding. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. format: float accountStatus: type: string description: >- The account's status: active, frozen, closed, suspended, restricted or dormant. beneficialOwnerRiskTier: type: string description: >- The highest risk tier among the beneficial owners or directors. productLimit: type: number description: >- The configured transaction and daily limit for the account or product. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. format: float internalBlacklistFlag: type: boolean description: >- true when the party is blocked because of a previously confirmed risk. account: type: object description: >- The account the money is debited from. Optional; when sent, currency and type are required. properties: id: type: string description: >- The account identifier. Send IBANs in upper case with no spaces. scheme: type: string description: How the account id is formatted. name: type: string description: >- The account holder's name, when it differs from the party's name. balance: oneOf: - type: number - type: string description: >- The account's balance when the transaction was made, in the account's currency, as a number or a decimal string. Rules read it as the Account Balance variable. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. currency: type: string description: >- ISO 4217 currency of the sender's account, for example NGN. maxLength: 3 minLength: 3 type: type: string description: >- ISO cash account type, for example CACC (current) or SVGS (savings). required: - currency - type bank: type: object description: >- The sender's bank. Optional; when sent, name and countryCode are required. properties: bic: type: string description: >- The bank's SWIFT code (ISO 9362), 8 or 11 characters. It is screened against sanctioned institutions and high-risk countries. pattern: ^(?:[A-Za-z0-9]{8}|[A-Za-z0-9]{11})$ clearingMemberId: type: string description: >- The bank's domestic clearing identifier, for example a bank or NIBSS code. lei: type: string description: The bank's Legal Entity Identifier, 20 characters. maxLength: 20 minLength: 20 address: type: object description: The bank's postal address. properties: country: type: string description: >- ISO 3166-1 alpha-2 country code. Required whenever an address is sent. maxLength: 2 minLength: 2 streetName: type: string description: Street name (up to 70 characters). maxLength: 70 buildingNumber: type: string description: Building number (up to 16 characters). maxLength: 16 buildingName: type: string description: Building name (up to 35 characters). maxLength: 35 floor: type: string description: Floor or level (up to 70 characters). maxLength: 70 postCode: type: string description: Postal or ZIP code (up to 16 characters). maxLength: 16 townName: type: string description: City or town (up to 35 characters). maxLength: 35 districtName: type: string description: District or neighbourhood (up to 35 characters). maxLength: 35 countrySubdivision: type: string description: >- State, province or region, for example LA for Lagos (up to 35 characters). maxLength: 35 department: type: string description: Department (up to 70 characters). maxLength: 70 subDepartment: type: string description: Sub-department (up to 70 characters). maxLength: 70 addressLines: type: array description: >- Up to 7 free-text address lines of up to 70 characters each. Use only when you cannot send the structured fields above. string maxLength: 70] items: {} maxItems: 7 required: - country name: type: string description: Name of the sender's bank (up to 140 characters). maxLength: 140 countryCode: type: string description: ISO 3166-1 alpha-2 country the sender's bank is in. maxLength: 2 minLength: 2 required: - name - countryCode required: - entityType beneficiaries: type: array description: >- The parties credited: at least one. A card transaction has exactly one, the merchant. { items: type: object description: >- A party that is credited, with the payment item allocated to it. properties: entityId: type: string description: >- Our id for the party. Send it whenever you have it: it skips the lookup. maxLength: 128 entityType: type: string description: 'What the party is: INDIVIDUAL or BUSINESS.' enum: - INDIVIDUAL - BUSINESS externalEntityId: type: string description: >- Your own id for the party. Required when entityId is not sent. maxLength: 128 name: type: string description: >- The party's full legal name (up to 140 characters). Required when entityId is not sent. maxLength: 140 accountNumber: type: string description: >- The party's account number. Used to find or create the party when entityId is not sent, which is when it is required. nationality: type: string description: >- ISO 3166-1 alpha-2 nationality; for a business, its country of incorporation. maxLength: 2 minLength: 2 countryOfResidence: type: string description: ISO 3166-1 alpha-2 country the party lives in. maxLength: 2 minLength: 2 dateOfBirth: type: string description: Date of birth, YYYY-MM-DD (individuals only). pattern: ^\d{4}-\d{2}-\d{2}$ placeOfBirth: type: object description: Where the party was born (individuals only). properties: city: type: string description: City of birth. country: type: string description: ISO 3166-1 alpha-2 country of birth. maxLength: 2 minLength: 2 address: type: object description: The party's postal address. properties: country: type: string description: >- ISO 3166-1 alpha-2 country code. Required whenever an address is sent. maxLength: 2 minLength: 2 streetName: type: string description: Street name (up to 70 characters). maxLength: 70 buildingNumber: type: string description: Building number (up to 16 characters). maxLength: 16 buildingName: type: string description: Building name (up to 35 characters). maxLength: 35 floor: type: string description: Floor or level (up to 70 characters). maxLength: 70 postCode: type: string description: Postal or ZIP code (up to 16 characters). maxLength: 16 townName: type: string description: City or town (up to 35 characters). maxLength: 35 districtName: type: string description: District or neighbourhood (up to 35 characters). maxLength: 35 countrySubdivision: type: string description: >- State, province or region, for example LA for Lagos (up to 35 characters). maxLength: 35 department: type: string description: Department (up to 70 characters). maxLength: 70 subDepartment: type: string description: Sub-department (up to 70 characters). maxLength: 70 addressLines: type: array description: >- Up to 7 free-text address lines of up to 70 characters each. Use only when you cannot send the structured fields above. string maxLength: 70] items: {} maxItems: 7 required: - country identification: type: array description: >- Government or organisation identifiers for the party. { items: type: object description: One government or organisation identifier. properties: scheme: type: string description: >- The kind of identifier, for example BVN, NIN or PASSPORT. id: type: string description: The identifier itself. issuerCountry: type: string description: ISO 3166-1 alpha-2 country that issued it. maxLength: 2 minLength: 2 issueDate: type: string description: When it was issued, YYYY-MM-DD. pattern: ^\d{4}-\d{2}-\d{2}$ expiryDate: type: string description: When it expires, YYYY-MM-DD. pattern: ^\d{4}-\d{2}-\d{2}$ account: type: object description: The account involved in the transaction. properties: id: type: string description: >- The account identifier. Send IBANs in upper case with no spaces. scheme: type: string description: How the account id is formatted. currency: type: string description: ISO 4217 currency of the account, for example NGN. maxLength: 3 minLength: 3 type: type: string description: >- ISO cash account type, for example CACC (current) or SVGS (savings). name: type: string description: >- The account holder's name, when it differs from the party's name. balance: oneOf: - type: number - type: string description: >- The account's balance when the transaction was made, in the account's currency, as a number or a decimal string. Rules read it as the Account Balance variable. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. bank: type: object description: The party's bank. properties: name: type: string description: >- Name of the bank or institution (up to 140 characters). maxLength: 140 countryCode: type: string description: ISO 3166-1 alpha-2 country the bank is in. maxLength: 2 minLength: 2 bic: type: string description: >- The bank's SWIFT code (ISO 9362), 8 or 11 characters. It is screened against sanctioned institutions and high-risk countries. pattern: ^(?:[A-Za-z0-9]{8}|[A-Za-z0-9]{11})$ clearingMemberId: type: string description: >- The bank's domestic clearing identifier, for example a bank or NIBSS code. lei: type: string description: The bank's Legal Entity Identifier, 20 characters. maxLength: 20 minLength: 20 address: type: object description: The bank's postal address. properties: country: type: string description: >- ISO 3166-1 alpha-2 country code. Required whenever an address is sent. maxLength: 2 minLength: 2 streetName: type: string description: Street name (up to 70 characters). maxLength: 70 buildingNumber: type: string description: Building number (up to 16 characters). maxLength: 16 buildingName: type: string description: Building name (up to 35 characters). maxLength: 35 floor: type: string description: Floor or level (up to 70 characters). maxLength: 70 postCode: type: string description: Postal or ZIP code (up to 16 characters). maxLength: 16 townName: type: string description: City or town (up to 35 characters). maxLength: 35 districtName: type: string description: >- District or neighbourhood (up to 35 characters). maxLength: 35 countrySubdivision: type: string description: >- State, province or region, for example LA for Lagos (up to 35 characters). maxLength: 35 department: type: string description: Department (up to 70 characters). maxLength: 70 subDepartment: type: string description: Sub-department (up to 70 characters). maxLength: 70 addressLines: type: array description: >- Up to 7 free-text address lines of up to 70 characters each. Use only when you cannot send the structured fields above. string maxLength: 70] items: {} maxItems: 7 required: - country ultimateParty: type: object description: >- The real originator or beneficiary, where different from this party. It is screened. contact: type: object description: How to reach the party. Used for link analysis only. properties: email: type: string description: The party's email address. format: email phone: type: string description: >- The party's phone number, for example +2348012345678. riskRating: type: string description: >- Your own risk rating for the party, for example low, medium or high. Used as the customer's risk rating when we have none (variable Risk Rating). accountAge: type: number description: >- How long the account has been open, in the unit you give in accountAgeUnit. Send the two together. The Account Age variable holds whole years, so it is worked out as days ÷ 365, weeks ÷ 52 or months ÷ 12, rounded down. format: float accountAgeUnit: type: string description: >- The unit accountAge is stated in: days, weeks, months or years. You choose it; send it with accountAge. enum: - days - weeks - months - years expectedMonthlyVolume: type: number description: >- The transaction volume expected each month, declared or assigned at onboarding. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. format: float accountStatus: type: string description: >- The account's status: active, frozen, closed, suspended, restricted or dormant. beneficialOwnerRiskTier: type: string description: >- The highest risk tier among the beneficial owners or directors. productLimit: type: number description: >- The configured transaction and daily limit for the account or product. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. format: float internalBlacklistFlag: type: boolean description: >- true when the party is blocked because of a previously confirmed risk. transferDetails: type: object description: >- This beneficiary's part of the payment: a payment item. properties: paymentItemId: type: string description: >- Identifies this payment item: this beneficiary's share of the payment. Must be unique within the message when sent. amount: oneOf: - type: number - type: string pattern: ^(?:\d+|\d+\.\d+)$ description: >- Amount allocated to this beneficiary, in the debit currency (financials.currency). Greater than zero; the amounts of all beneficiaries must add up to financials.totalAmount. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. currency: type: string description: >- ISO 4217 currency of amount. Must equal financials.currency. maxLength: 3 minLength: 3 endToEndId: type: string description: >- Optional. A reference the sender gives this payment item that stays the same through every bank and payment system it passes through, so the one payment can be traced end to end (ISO 20022 EndToEndId, up to 35 characters). For a card payment it is the retrieval reference number (RRN). maxLength: 35 instructionId: type: string description: >- Optional. Your own internal reference for this instruction (up to 35 characters). Unlike endToEndId, it is not passed on to other banks. maxLength: 35 uetr: type: string description: >- Optional. The unique end-to-end transaction reference: a UUID v4 that identifies one cross-border payment on the SWIFT network, the same for every bank on its route. Domestic payments, such as NIP, do not have one. format: uuid baseAmount: oneOf: - type: number - type: string description: >- This item's amount converted to baseCurrency. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. baseCurrency: type: string description: >- ISO 4217 house base currency of baseAmount, typically USD. maxLength: 3 minLength: 3 creditAmount: oneOf: - type: number - type: string description: >- The amount the beneficiary receives in their own currency (creditCurrency), when a currency conversion applies. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. creditCurrency: type: string description: ISO 4217 currency of creditAmount. maxLength: 3 minLength: 3 purposeCode: type: string description: >- Why this payment is made (ISO External Purpose code), for example SUPP (supplier), SALA (salary) or TRAD (trade). remittanceInfo: type: string description: >- Free-text narrative or invoice reference for the payment (up to 140 characters). maxLength: 140 required: - amount - currency required: - entityType - transferDetails minItems: 1 required: - sender - beneficiaries isInternational: type: boolean description: >- Optional. Whether the transaction crosses a border. You decide; the platform never works it out from the countries. When left out, the transaction is not treated as international. isNight: type: boolean description: >- Optional. Whether the transaction happened at night. You decide; the platform never works it out from the time. When left out, the transaction is not treated as a night transaction. creationDateTime: type: string description: When the transaction was created at the source (UTC, ISO 8601). intermediaryBanks: type: array description: >- Up to 3 intermediary banks the payment passes through, in order. They are screened. { items: type: object description: A bank or other financial institution. properties: name: type: string description: Name of the bank or institution (up to 140 characters). maxLength: 140 countryCode: type: string description: ISO 3166-1 alpha-2 country the bank is in. maxLength: 2 minLength: 2 bic: type: string description: >- The bank's SWIFT code (ISO 9362), 8 or 11 characters. It is screened against sanctioned institutions and high-risk countries. pattern: ^(?:[A-Za-z0-9]{8}|[A-Za-z0-9]{11})$ clearingMemberId: type: string description: >- The bank's domestic clearing identifier, for example a bank or NIBSS code. lei: type: string description: The bank's Legal Entity Identifier, 20 characters. maxLength: 20 minLength: 20 address: type: object description: The bank's postal address. properties: country: type: string description: >- ISO 3166-1 alpha-2 country code. Required whenever an address is sent. maxLength: 2 minLength: 2 streetName: type: string description: Street name (up to 70 characters). maxLength: 70 buildingNumber: type: string description: Building number (up to 16 characters). maxLength: 16 buildingName: type: string description: Building name (up to 35 characters). maxLength: 35 floor: type: string description: Floor or level (up to 70 characters). maxLength: 70 postCode: type: string description: Postal or ZIP code (up to 16 characters). maxLength: 16 townName: type: string description: City or town (up to 35 characters). maxLength: 35 districtName: type: string description: District or neighbourhood (up to 35 characters). maxLength: 35 countrySubdivision: type: string description: >- State, province or region, for example LA for Lagos (up to 35 characters). maxLength: 35 department: type: string description: Department (up to 70 characters). maxLength: 70 subDepartment: type: string description: Sub-department (up to 70 characters). maxLength: 70 addressLines: type: array description: >- Up to 7 free-text address lines of up to 70 characters each. Use only when you cannot send the structured fields above. string maxLength: 70] items: {} maxItems: 7 required: - country maxItems: 3 regulatoryReporting: type: array description: >- Codes an authority requires you to report with the transaction. { items: type: object description: One reporting code for one authority. properties: authorityCountry: type: string description: ISO 3166-1 alpha-2 country of the reporting authority. maxLength: 2 minLength: 2 detailsCode: type: string description: A code the authority defines. detailsText: type: string description: Free text (up to 35 characters per line). isoRef: type: string description: >- The ISO 20022 message the transaction maps to, for example pacs.008. Informational. card: type: object description: >- Card details. Required when paymentType.channel is CARD, and not allowed otherwise. properties: panToken: type: string description: >- A token standing in for the card number. Never send the raw PAN. bin: type: string description: >- The first 6 to 8 digits of the card number (the bank identification number). pattern: ^\d{6,8}$ cardScheme: type: string description: The card network. cardType: type: string description: The kind of card. cardCountry: type: string description: ISO 3166-1 alpha-2 country that issued the card. maxLength: 2 minLength: 2 authType: type: string description: The kind of authorisation message. entryMode: type: string description: >- How the card was read: CHIP, CONTACTLESS, SWIPE, MANUAL, ECOM (online), TOKEN_WALLET or FALLBACK. enum: - CHIP - CONTACTLESS - SWIPE - MANUAL - ECOM - TOKEN_WALLET - FALLBACK cvvResult: type: string description: The result of the card security code check. stan: type: string description: System trace audit number (ISO 8583 field 11). rrn: type: string description: Retrieval reference number (ISO 8583 field 37). mcc: type: string description: The merchant category code (ISO 8583 field 18). merchantId: type: string description: The card acceptor (merchant) id (ISO 8583 field 42). terminalId: type: string description: The terminal id (ISO 8583 field 41). acquirerId: type: string description: The acquiring institution id (ISO 8583 field 32). transmissionDateTime: type: string description: >- When the message was transmitted (ISO 8583 field 7), ISO 8601. cardholderPresent: type: boolean description: Whether the cardholder was physically present. isCrossBorder: type: boolean description: >- Whether the card's country differs from the merchant's country. threeDSecure: type: object description: >- The 3-D Secure (online payment authentication) result. Required for ECOM. properties: status: type: string description: >- The 3-D Secure outcome: Y authenticated, N failed, A attempted, U unavailable, R rejected. enum: - 'Y' - 'N' - A - U - R eci: type: string description: >- The two-digit electronic commerce indicator the card network returns, for example 05. version: type: string description: The 3-D Secure version, for example 2.2.0. posConditionCode: type: string description: >- Point-of-sale condition code: whether the card was present (ISO 8583 field 25). pinVerified: type: boolean description: Whether the PIN was verified. required: - panToken - bin - cardScheme - authType - entryMode - stan - rrn - mcc - merchantId - terminalId - acquirerId - transmissionDateTime - cardholderPresent - isCrossBorder status: type: string description: Whether the transaction completed, is pending, or failed. settled_at: type: string description: When the transaction settled, if it has. format: date-time processed_at: type: string description: When the platform received or processed the transaction. format: date-time fee_amount: oneOf: - type: number - type: string description: >- The transaction fee, network fee, FX fee or service charge, as a number or a decimal string. In the currency's main unit, not its smallest one: naira, not kobo; dollars, not cents. Use decimals for the fraction, so 1500.50 is 1,500 naira and 50 kobo. process_method: type: string description: >- The raw, un-normalised value from your platform for how the transaction was processed. is_approved: type: boolean description: Whether the transaction was approved. is_reversal: type: boolean description: Whether this transaction reverses an earlier one. is_international_override: type: boolean description: >- Whether the transaction crosses a border, when you want to override isInternational for this one variable. is_triggered_by_user: type: boolean description: >- Whether the user initiated the transaction directly, as opposed to the system or a schedule. is_round_amount: type: boolean description: >- Whether the amount is a round figure, for example 1,000, 5,000 or 10,000. is_large_transaction: type: boolean description: >- Whether the amount exceeds a limit set by the bank, customer or product. counterparty: type: object description: >- What you know about the counterparty that we cannot work out from the parties themselves. properties: industry: type: object description: The counterparty's industry. properties: code: type: string description: The counterparty's industry or merchant category code. is_linked_account: type: boolean description: >- Whether the counterparty's account is linked to the sender's own profile. is_new: type: boolean description: Whether the entity has never used this counterparty before. age_days: type: number description: How long the counterparty relationship has existed, in days. format: float risk_tier: type: string description: The risk score or tier you assigned the counterparty. is_watchlisted: type: boolean description: >- Whether the counterparty is on an internal or external watchlist. device: type: object description: The digital channel the transaction came through. properties: is_proxy: type: boolean description: >- Whether the device's IP address appears to use a VPN, proxy or TOR. ipAddress: type: string description: The client's public IP address (IPv4 or IPv6). geoCountry: type: string description: >- ISO 3166-1 alpha-2 country the device reports or the IP address maps to. maxLength: 2 minLength: 2 sessionId: type: string description: Your reference for the session. deviceFingerprint: type: string description: >- A stable identifier for the device. It is compared with the entity's last login device. userAgent: type: string description: The raw user agent string. geo: type: object description: The device's position. properties: lat: type: number description: Latitude in degrees, -90 to 90. format: float lon: type: number description: Longitude in degrees, -180 to 180. format: float accuracyM: type: number description: How accurate the position is, in metres. format: float channelApp: type: string description: The app or channel the customer used. enum: - MOBILE_APP - WEB - USSD - ATM - POS - BRANCH - API crypto: type: object description: Details of a crypto transaction. properties: asset_type: type: string description: >- The crypto asset, for example BTC, ETH, USDT, a stablecoin, a privacy coin or an NFT. wallet_address: type: string description: The origin or destination blockchain address. travel_rule_complete: type: boolean description: >- Whether the originator and beneficiary information the travel rule requires is complete. mixer_exposure: type: boolean description: >- Whether the wallet address has direct or indirect exposure to a mixer or tumbler. sanctioned_address_exposure: type: boolean description: >- Whether the wallet address has exposure to a sanctioned wallet, address or entity. transactionReference: type: string description: >- Your unique reference for this transaction. It identifies the transaction, not the event: the idempotency key is the event's externalEventId. required: - paymentType - financials - parties - creationDateTime - transactionReference required: - eventType - externalEventId - eventStatus - eventCategory - data LoginEvent: type: object description: >- TM account-activity event for a login (data.loginMethod; routed by eventCategory). properties: eventType: type: string description: >- The kind of event: transaction or account_activity (a login or a card event). enum: - account_activity example: account_activity schemaVersion: type: string description: Version of this payload schema. Only major version 1 is supported. pattern: ^1\.\d+$|^1\.\d+\.\d+$ example: '1.2' externalEventId: type: string description: >- 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. maxLength: 128 eventStatus: type: string description: >- 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. enum: - acknowledged - pending - completed - attempted - successful - requested - issued - activated - frozen - suspended - unfrozen - pin_changed - closed - canceled - failed - reversed example: acknowledged lifecycleId: type: string description: >- Your identifier tying together several events that belong to the same lifecycle, for example one session or one payment. maxLength: 128 metadata: type: object description: >- Information about the event itself, the same on every event type. Any other key you add is kept and passed on. properties: source: type: string description: The system the event came from, for example core-banking. appVersion: type: string description: The version of your app that sent the event. traceId: type: string description: 'A W3C trace id: 32 hex characters.' pattern: ^[0-9a-fA-F]{32}$ testMode: type: boolean description: >- true evaluates and logs the event but never acts on it (no alerts, cases or shadow runs). eventCategory: type: string description: >- Routes the event to the workflows tagged with this category, for example finance or kyc. enum: - finance - kyc - travel_rule - user_event - gambling - audit_trail_event - crypto - insurance - investment data: type: object description: >- A login or a card event: one flat object. A login carries loginMethod, a card event cardAction. properties: entityId: type: string description: >- Our id for the customer. Send it whenever you have it: it skips the lookup. entityType: type: string description: 'What the customer is: INDIVIDUAL or BUSINESS.' enum: - INDIVIDUAL - BUSINESS externalEntityId: type: string description: >- Your own id for the customer. Required when entityId is not sent. name: type: string description: The customer's full name. Required when entityId is not sent. accountNumber: type: string description: >- The customer's account number. Used to find or create the customer when entityId is not sent, which is when it is required. loginMethod: type: string description: >- How the customer logged in. Its presence makes this a login event; a card event carries cardAction instead, and exactly one of the two is required. enum: - biometric - password - sso - passwordless cardAction: type: string description: >- Whether a card was created or updated. Its presence makes this a card event; a login carries loginMethod instead, and exactly one of the two is required. enum: - created - updated timestamp: type: string description: >- When it happened (ISO 8601). Required for a card event; for a login it defaults to the time the event is received. format: date-time externalLoginId: type: string description: Your own id for this login. externalSessionId: type: string description: Your own id for the session the login opened, or null. nullable: true username: type: string description: The username used to log in. sso: type: string description: The single-sign-on provider, when loginMethod is sso. enum: - okta - google - apple loginStatus: type: string description: >- How this login attempt went. This is a field of the login; the event's own eventStatus is separate. enum: - attempted - failed - mfa - rejected - successful device: type: object description: The device the login was made from. properties: registeredDevice: type: boolean description: >- Whether the device is one the customer has registered with you. externalDeviceId: type: string description: Your own stable id for the device. ipAddressV4: type: string description: The client's public IPv4 address. ipAddressV6: type: string description: The client's public IPv6 address. ipAddressLatitude: type: number description: Latitude of the place the IP address maps to. format: float ipAddressLongitude: type: number description: Longitude of the place the IP address maps to. format: float ipAddressCity: type: string description: City the IP address maps to. ipAddressRegion: type: string description: State or region the IP address maps to. ipAddressCountryCode: type: string description: >- ISO 3166-1 alpha-2 country the IP address maps to, for example NG. deviceIsp: type: string description: >- The internet service provider or mobile operator, for example MTN Nigeria. maxLength: 2048 deviceType: type: string description: The kind of device, for example mobile or desktop. deviceOs: type: string description: The operating system and its version, for example iOS 18.1. screenResolution: type: string description: The screen size in pixels, for example 1179x2556. timezoneOffset: type: string description: The device's offset from UTC, for example +01:00. browserType: type: string description: The browser, for example Safari. browserVersion: type: string description: The browser's version, for example 18.1. browserLanguage: type: string description: The browser's language, for example en-NG. cookiesEnabled: type: string description: >- Whether cookies are enabled: true or false, or not available, excluded or error when it could not be read. enum: - 'true' - 'false' - not available - excluded - error javascriptEnabled: type: string description: >- Whether JavaScript is enabled: true or false, or not available, excluded or error when it could not be read. enum: - 'true' - 'false' - not available - excluded - error firstSeenAt: type: string description: When you first saw this device (ISO 8601). format: date-time newDevice: type: boolean description: Whether this device is new to the customer. credentialChangeType: type: string description: What was changed in the session this login opened. enum: - password - email - phone - mfa_device - username externalCardId: type: string description: Your own id for the card. cardName: type: string description: The name shown on the card. productName: type: string description: >- The name of the card product, for example Platinum Virtual Debit. productCode: type: string description: Your code for the card product. cardType: type: string description: The kind of card. enum: - debit - credit - prepaid - charge formFactor: type: string description: Whether the card is physical or virtual. enum: - physical - virtual issuedAt: type: string description: When the card was issued (ISO 8601). format: date-time expiryMonth: type: string description: The month the card expires, 1 to 12 or 01 to 12. pattern: ^(0?[1-9]|1[0-2])$ expiryYear: type: string description: The year the card expires, four digits. pattern: ^\d{4}$ pinUpdatedAt: type: string description: When the card's PIN was last changed (ISO 8601). format: date-time pinUpdateMethod: type: string description: How the PIN was changed. enum: - app - ivr - agent - atm - other isLocked: type: boolean description: Whether the card is locked. lockExpiresAt: type: string description: When the lock on the card ends (ISO 8601). format: date-time cardStatus: type: string description: >- The card's status. This is a field of the card; the event's own eventStatus is separate. enum: - active - inactive - deactivated - terminated - pending_activation - expired statusDetail: type: string description: >- Free text explaining the card's status, for example Awaiting first use. channel: type: string description: The channel the card event came through, for example mobile-app. role: type: string description: What the entity is to the card, for example primary. currency: type: string description: ISO 4217 currency of the account. maxLength: 3 minLength: 3 replacesExternalCardId: type: string description: Your id of the card this one replaces, when it is a replacement. replacementReason: type: string description: Why the card was replaced, for example lost. required: - entityType required: - eventType - externalEventId - eventStatus - eventCategory - data CardEvent: type: object description: >- TM account-activity event for a card (data.cardAction; routed by eventCategory). properties: eventType: type: string description: >- The kind of event: transaction or account_activity (a login or a card event). enum: - account_activity example: account_activity schemaVersion: type: string description: Version of this payload schema. Only major version 1 is supported. pattern: ^1\.\d+$|^1\.\d+\.\d+$ example: '1.2' externalEventId: type: string description: >- 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. maxLength: 128 eventStatus: type: string description: >- 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. enum: - acknowledged - pending - completed - attempted - successful - requested - issued - activated - frozen - suspended - unfrozen - pin_changed - closed - canceled - failed - reversed example: acknowledged lifecycleId: type: string description: >- Your identifier tying together several events that belong to the same lifecycle, for example one session or one payment. maxLength: 128 metadata: type: object description: >- Information about the event itself, the same on every event type. Any other key you add is kept and passed on. properties: source: type: string description: The system the event came from, for example core-banking. appVersion: type: string description: The version of your app that sent the event. traceId: type: string description: 'A W3C trace id: 32 hex characters.' pattern: ^[0-9a-fA-F]{32}$ testMode: type: boolean description: >- true evaluates and logs the event but never acts on it (no alerts, cases or shadow runs). eventCategory: type: string description: >- Routes the event to the workflows tagged with this category, for example finance or kyc. enum: - finance - kyc - travel_rule - user_event - gambling - audit_trail_event - crypto - insurance - investment data: type: object description: >- A login or a card event: one flat object. A login carries loginMethod, a card event cardAction. properties: entityId: type: string description: >- Our id for the customer. Send it whenever you have it: it skips the lookup. entityType: type: string description: 'What the customer is: INDIVIDUAL or BUSINESS.' enum: - INDIVIDUAL - BUSINESS externalEntityId: type: string description: >- Your own id for the customer. Required when entityId is not sent. name: type: string description: The customer's full name. Required when entityId is not sent. accountNumber: type: string description: >- The customer's account number. Used to find or create the customer when entityId is not sent, which is when it is required. loginMethod: type: string description: >- How the customer logged in. Its presence makes this a login event; a card event carries cardAction instead, and exactly one of the two is required. enum: - biometric - password - sso - passwordless cardAction: type: string description: >- Whether a card was created or updated. Its presence makes this a card event; a login carries loginMethod instead, and exactly one of the two is required. enum: - created - updated timestamp: type: string description: >- When it happened (ISO 8601). Required for a card event; for a login it defaults to the time the event is received. format: date-time externalLoginId: type: string description: Your own id for this login. externalSessionId: type: string description: Your own id for the session the login opened, or null. nullable: true username: type: string description: The username used to log in. sso: type: string description: The single-sign-on provider, when loginMethod is sso. enum: - okta - google - apple loginStatus: type: string description: >- How this login attempt went. This is a field of the login; the event's own eventStatus is separate. enum: - attempted - failed - mfa - rejected - successful device: type: object description: The device the login was made from. properties: registeredDevice: type: boolean description: >- Whether the device is one the customer has registered with you. externalDeviceId: type: string description: Your own stable id for the device. ipAddressV4: type: string description: The client's public IPv4 address. ipAddressV6: type: string description: The client's public IPv6 address. ipAddressLatitude: type: number description: Latitude of the place the IP address maps to. format: float ipAddressLongitude: type: number description: Longitude of the place the IP address maps to. format: float ipAddressCity: type: string description: City the IP address maps to. ipAddressRegion: type: string description: State or region the IP address maps to. ipAddressCountryCode: type: string description: >- ISO 3166-1 alpha-2 country the IP address maps to, for example NG. deviceIsp: type: string description: >- The internet service provider or mobile operator, for example MTN Nigeria. maxLength: 2048 deviceType: type: string description: The kind of device, for example mobile or desktop. deviceOs: type: string description: The operating system and its version, for example iOS 18.1. screenResolution: type: string description: The screen size in pixels, for example 1179x2556. timezoneOffset: type: string description: The device's offset from UTC, for example +01:00. browserType: type: string description: The browser, for example Safari. browserVersion: type: string description: The browser's version, for example 18.1. browserLanguage: type: string description: The browser's language, for example en-NG. cookiesEnabled: type: string description: >- Whether cookies are enabled: true or false, or not available, excluded or error when it could not be read. enum: - 'true' - 'false' - not available - excluded - error javascriptEnabled: type: string description: >- Whether JavaScript is enabled: true or false, or not available, excluded or error when it could not be read. enum: - 'true' - 'false' - not available - excluded - error firstSeenAt: type: string description: When you first saw this device (ISO 8601). format: date-time newDevice: type: boolean description: Whether this device is new to the customer. credentialChangeType: type: string description: What was changed in the session this login opened. enum: - password - email - phone - mfa_device - username externalCardId: type: string description: Your own id for the card. cardName: type: string description: The name shown on the card. productName: type: string description: >- The name of the card product, for example Platinum Virtual Debit. productCode: type: string description: Your code for the card product. cardType: type: string description: The kind of card. enum: - debit - credit - prepaid - charge formFactor: type: string description: Whether the card is physical or virtual. enum: - physical - virtual issuedAt: type: string description: When the card was issued (ISO 8601). format: date-time expiryMonth: type: string description: The month the card expires, 1 to 12 or 01 to 12. pattern: ^(0?[1-9]|1[0-2])$ expiryYear: type: string description: The year the card expires, four digits. pattern: ^\d{4}$ pinUpdatedAt: type: string description: When the card's PIN was last changed (ISO 8601). format: date-time pinUpdateMethod: type: string description: How the PIN was changed. enum: - app - ivr - agent - atm - other isLocked: type: boolean description: Whether the card is locked. lockExpiresAt: type: string description: When the lock on the card ends (ISO 8601). format: date-time cardStatus: type: string description: >- The card's status. This is a field of the card; the event's own eventStatus is separate. enum: - active - inactive - deactivated - terminated - pending_activation - expired statusDetail: type: string description: >- Free text explaining the card's status, for example Awaiting first use. channel: type: string description: The channel the card event came through, for example mobile-app. role: type: string description: What the entity is to the card, for example primary. currency: type: string description: ISO 4217 currency of the account. maxLength: 3 minLength: 3 replacesExternalCardId: type: string description: Your id of the card this one replaces, when it is a replacement. replacementReason: type: string description: Why the card was replaced, for example lost. required: - entityType required: - eventType - externalEventId - eventStatus - eventCategory - data OnboardingEvent: type: object description: >- Customer Onboarding (CO) event. Routed by `workflowId` and `workflowVersion`, not by `eventCategory`. required: - eventType - externalEventId - eventStatus - workflowId - workflowVersion - data properties: eventType: type: string enum: - onboarding description: >- The kind of event. Always `onboarding` for a Customer Onboarding event. example: onboarding externalEventId: type: string description: >- 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. maxLength: 128 eventStatus: type: string description: Where the event is in its life. example: pending workflowId: type: string description: >- The id of the Customer Onboarding workflow to run. Copy it from the workflow's request payload in Cowork. example: wfw_6aec90ccc34dc00ea4303800 workflowVersion: type: integer description: The version of the workflow to run. example: 1 metadata: type: object description: Free-form metadata about the event. additionalProperties: true data: type: object description: >- The entity being onboarded, plus any extra fields the workflow's Initiator node asks for. required: - externalEntityId - entityType properties: externalEntityId: type: string description: Your own id for the entity being onboarded. entityId: type: string description: >- Youverify entity id. Send it when the workflow is for an existing entity. entityType: type: string enum: - INDIVIDUAL - BUSINESS description: 'What the entity is: INDIVIDUAL or BUSINESS.' additionalProperties: true SendEventResponse: type: object properties: success: type: boolean example: true statusCode: type: integer enum: - 202 example: 202 message: type: string enum: - Event accepted example: Event accepted data: type: object properties: eventId: type: string eventType: type: string eventCategory: type: string nullable: true eventStatus: type: string description: >- PROCESSING while an evaluation the event started is still running, else PROCESSED. The event's own status (acknowledged, completed...) is on the thread. enum: - PROCESSING - PROCESSED externalEventId: type: string nullable: true evaluations: type: array items: type: object properties: id: type: string status: type: string enum: - PENDING - RUNNING - PAUSED - SUCCESS - SUCCESS_PENDING_AML_CHECK - SUCCESS_PENDING_CASE_RESOLUTION - FAILED decision: type: string nullable: true enum: - BLOCK - FREEZE - HOLD - REVIEW - ALERT - ALLOW decisionReason: type: string nullable: true decisionFinal: type: boolean riskScore: type: number format: float nullable: true actionsApplied: type: array items: type: string outcome: type: object properties: result: type: string nullable: true enum: - approved - denied - manual_review - pending - no_action_defined flagged: type: array items: type: string required: - result - flagged entityId: type: string description: >- CO evaluations only: the entity onboarded; null until a new one is known nullable: true entityName: type: string description: CO evaluations only nullable: true workflow: type: object properties: id: type: string type: type: string enum: - TM_WORKFLOW monitoringType: type: string description: >- REALTIME blocks in-stream; T_PLUS_1 runs after the transaction. Null for a backtest. nullable: true enum: - REALTIME - T_PLUS_1 version: oneOf: - type: integer - type: string enum: - DRAFT required: - id - type - monitoringType - version timing: type: object properties: startedAt: type: string format: date-time nullable: true executionTimeMs: type: number format: float nullable: true required: - startedAt - executionTimeMs lifecycleState: type: string description: >- Where the evaluation stands after the engine ran; status is the engine's own. enum: - COMPLETED - IN_PROGRESS - PENDING_AML_CHECK - PENDING_CASE_RESOLUTION - FAILED riskProfile: type: object description: The risk profile behind the score. properties: score: type: number description: Overall risk score. contributingFactors: type: array description: What contributed to the score. items: type: object properties: factor: type: string score: type: number rulesMatched: type: array items: type: object properties: ruleId: type: string nodeId: type: string valueTriggered: type: number description: The value at risk format: float required: - ruleId - nodeId - valueTriggered actions: type: array items: type: object properties: actionType: type: string details: type: string nullable: true required: - actionType - details required: - id - status - decision - decisionReason - decisionFinal - riskScore - actionsApplied - outcome count: type: integer replayed: type: boolean required: - eventId - eventType - eventCategory - eventStatus - externalEventId - evaluations - count - replayed links: type: array items: type: object required: - success - statusCode - message - data 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.