Send Events for Fraud Monitoring

Request

Real-time URL

[POST]

https://ingest.dojah.io/api/ingest

A dedicated API endpoint that you send data to as events happen (e.g., a user login, transaction, or account creation). Dojah immediately analyzes the event for suspicious patterns — velocity checks, IP reputation, device fingerprinting — and returns a risk score or block decision within milliseconds. Typical use: Webhooks, user actions, payment attempts, and other live traffic.

Backfill

[POST]

https://ingest.dojah.io/api/ingest/backfill

A separate endpoint used to upload historical events that already occurred before you integrated Dojah’s real-time API. Fraud models often need past data to learn “normal” behavior (e.g., a user’s past login locations or transaction amounts). Without backfill, the real-time system may miss patterns that started earlier. Common use cases:

You have months of transaction logs stored in your database.
You send them via /api/ingest/backfill so Dojah can train and update risk rules retroactively.
After backfill is complete, you switch to the real-time URL for all new events.

Headers

Header	Type	Description
Authorization	string	Private/secret key. Use `<key>` not `Bearer <key>`

Check out the guide on how to Connect a Flow.

The key in the request body is your Ingest key, which is different from your Authorization secret key. You can find your Ingest key in the EasyDetect settings on your dashboard.

Request Body Template

The tables below describe the fields available in the request body for each use case. Fields marked Required must be included in every request; all other fields are Optional but recommended for more accurate fraud scoring.

Top-level Fields

Field	Type	Description	Applies To	Required
`key`	string	Your Ingest key from EasyDetect settings	Banking, Payments, Onboarding	Required
`type`	string	Event type: `banking`, `payments`, or `onboarding`	Banking, Payments, Onboarding	Required
`event`	object	Event payload containing the nested objects below	Banking, Payments, Onboarding	Required

event.transaction

Field	Type	Description	Applies To	Required
`id`	string	Unique transaction ID	Banking, Payments	Optional
`time`	string	Transaction timestamp in ISO 8601 format	Banking, Payments	Required
`amount`	number	Transaction amount	Banking, Payments	Optional
`currency`	string	Currency code (e.g., `XAF`, `NGN`)	Banking, Payments	Optional
`ref`	string	Transaction reference	Banking, Payments	Optional
`session_id`	string	Session identifier	Banking, Payments	Optional
`type`	string	Transaction type: `deposit`, `debit`, `credit`, `transfer`, `purchase`, `refund`, `withdrawal`	Banking, Payments	Optional
`channel`	string	Channel: `online`, `mobile`, `atm`, `branch`, `pos`	Banking, Payments	Optional
`purpose`	string	Purpose: `bill payment`, `transfer`, `airtime`, `salary payment`	Banking, Payments	Optional
`source_of_funds`	string	Source: `employment income`, `savings`, `business`, `investment`	Banking, Payments	Optional

event.user

Field	Type	Description	Applies To	Required
`user_id`	string	Unique user identifier	Banking, Payments, Onboarding	Optional
`user_type`	string	`individual`, `business`, `government`, `other`	Banking, Payments, Onboarding	Optional
`registration_time`	string	User registration timestamp in ISO 8601 format	Banking, Payments, Onboarding	Required
`email`	string	User email address	Banking, Payments, Onboarding	Optional
`name`	string	User full name	Banking, Payments, Onboarding	Optional
`dob`	string	Date of birth in `YYYY-MM-DD` format	Payments, Onboarding	Optional
`tier`	string	Account tier: `basic`, `silver`, `gold`, `platinum`	Banking, Payments, Onboarding	Optional
`account_type`	string	`savings`, `checking`, `business`, `student`	Banking, Payments, Onboarding	Optional
`gender`	string	`male`, `female`, `other`	Banking, Payments, Onboarding	Optional
`balance`	number	Current account balance before transaction	Banking, Payments, Onboarding	Optional
`mobile`	string	User phone number	Banking, Payments, Onboarding	Optional
`last_pin_change`	string	Last PIN change timestamp in ISO 8601 format	Banking, Payments, Onboarding	Optional
`last_password_change`	string	Last password change timestamp in ISO 8601 format	Banking, Payments, Onboarding	Optional
`credit_score`	string	User credit score	Payments, Onboarding	Optional
`employer_information`	object	Employment details (`annual_income`, `employment_status`, `employer_name`)	Payments, Onboarding	Optional
`kyc_information`	array	KYC documents, each with `id_number`, `id_type`, and `country`	Payments, Onboarding	Optional

event.receiver

Field	Type	Description	Applies To	Required
`account_name`	string	Receiver’s account name	Banking	Optional
`bank_name`	string	Receiver’s bank name	Banking	Optional
`account_number`	string	Receiver’s account number	Banking	Optional
`country`	string	Receiver’s country	Banking	Optional

event.sender

Field	Type	Description	Applies To	Required
`account_name`	string	Sender’s account name	Banking	Optional
`bank_name`	string	Sender’s bank name	Banking	Optional
`account_number`	string	Sender’s account number	Banking	Optional
`country`	string	Sender’s country	Banking	Optional

event.payment

Field	Type	Description	Applies To	Required
`payment_id`	string	Unique payment identifier	Payments	Optional
`is_recurring`	boolean	Whether the payment is recurring	Payments	Optional
`method_type`	string	Payment method: `card`, `ussd`, `transfer`	Payments	Optional
`scheme`	string	Card scheme (e.g., `Visa`, `Mastercard`)	Payments	Optional
`card_funding`	string	`credit` or `debit`	Payments	Optional
`card_last_four`	string	Last four digits of the card	Payments	Optional
`expiry_month`	string	Card expiry month	Payments	Optional
`expiry_year`	string	Card expiry year	Payments	Optional
`is_3ds_enabled`	boolean	Whether 3D Secure is enabled	Payments	Optional
`is_card_present`	boolean	Whether the physical card is present	Payments	Optional
`cvv_provided`	boolean	Whether CVV was provided	Payments	Optional
`avs_passed`	boolean	Whether AVS check passed	Payments	Optional
`name_on_card`	string	Cardholder name	Payments	Optional
`billing_address`	object	Billing address (`city`, `street`, `country`)	Payments	Optional

event.merchant

Field	Type	Description	Applies To	Required
`name`	string	Merchant name	Payments	Optional
`category`	string	Merchant category	Payments	Optional
`country`	string	Merchant country	Payments	Optional

event.device

Field	Type	Description	Applies To	Required
`type`	string	Device type (e.g., `mobile`, `desktop`)	Banking, Payments, Onboarding	Optional
`os`	string	Operating system (e.g., `Android`, `iOS`)	Banking, Payments, Onboarding	Optional
`model`	string	Device model (e.g., `Pixel 7`)	Banking, Payments, Onboarding	Optional
`language`	string	Device language (e.g., `en-US`)	Banking, Payments, Onboarding	Optional
`ip_address`	string	User’s IP address	Banking, Payments, Onboarding	Optional
`device_id`	string	Unique device identifier / fingerprint ID	Banking, Payments, Onboarding	Optional

event.address

Field	Type	Description	Applies To	Required
`city`	string	City name	Banking, Payments, Onboarding	Optional
`street`	string	Street address	Banking	Optional
`address1`	string	Primary address line	Payments, Onboarding	Optional
`address2`	string	Secondary address line	Payments, Onboarding	Optional
`region`	string	Region or state	Payments, Onboarding	Optional
`zipcode`	string	Postal / ZIP code	Payments, Onboarding	Optional
`country`	string	Country name	Banking, Payments, Onboarding	Optional

event.meta

Field	Type	Description	Applies To	Required
`meta`	array	Array of custom key-value pair objects for additional context	Banking	Optional

Transaction Monitoring - Use cases

Banking

Request body

{
   "key": "<your_ingest_key>",
   "type":"banking",  //banking, payments, onboarding
   "event":{
      "transaction":{
         "id": "87554303-3f75-4883-8fb8-48fce003859f", //unique transaction id
         "time": "2022-12-12T12:15:05.391Z", //ISO 8601 format
         "amount": 8291,
         "currency": "XAF",
         "ref": "xaf",
         "session_id": "xaf",
         "type": "deposit",  //debit, credit, transfer, etc.
         "channel": "mobile",  //online, mobile, atm, branch, pos
         "purpose": "salary payment",  //bill payment, transfer, airtime, etc.
         "source_of_funds": "employment income"  //savings, business, investment, etc.
      },
      "user":{
         "user_id":"9931fac0-6bfa-4b3c-842c-7840006d89b6",
         "user_type": "individual",  //individual, business, government, other
         "registration_time": "2022-12-12T12:15:05.392Z",
         "email":"erik.miller@buchanan.com",
         "name":"Trevor Arias",
         "tier": "silver",  //basic, silver, gold, platinum
         "account_type": "checking",  //savings, checking, business, student
         "gender": "male",  //male, female, other
         "balance": 24500.50,  //current account balance before transaction
         "mobile":"5797454931",
         "last_pin_change": "2022-11-01T08:30:00.000Z",
         "last_password_change": "2022-10-15T14:22:10.000Z"
      },
      "receiver":{
         "account_name": "John Doe",
         "bank_name": "EcoBank",
         "account_number": "CM21100375689",
         "country": "Cameroon"
      },
      "sender":{
         "account_name": "Anon Doe",
         "bank_name": "Paystack TITAN",
         "account_number": "NG0567890321",
         "country": "Nigeria"
      },
      "device":{
         "type":"mobile",
         "os":"Android",
         "model":"Pixel 7",
         "language":"en-US",
         "ip_address":"154.72.170.233",
         "device_id":"ff97adb7-8d3d-4f15-94df-87e21e1212de"
      },
      "address":{
         "city":"North Sarah",
         "street":"6238 Walker Unions Suite 802",
         "country":"Morocco"
      },
       "meta": [
        {"key": "value"}
      ]
   }
}

Payments

Request body

{
   "key": "<your_ingest_key>",
   "type":"payments",
   "event":{
      "user":{
               "user_id":"9931fac0-6bfa-4b3c-842c-7840006d89b6",
               "user_type": "individual",  //individual, business, government, other
               "registration_time": "2022-12-12T12:15:05.392Z",
               "email":"erik.miller@buchanan.com",
               "name":"Trevor Arias",
               "dob": "1980-01-01", //User's date of birth, YYYY-MM-DD format
               "tier": "silver",  //basic, silver, gold, platinum
               "account_type": "checking",  //savings, checking, business, student
               "gender": "male",  //male, female, other
               "balance": 24500.50,  //current account balance before transaction
               "mobile":"5797454931",
               "last_pin_change": "2022-11-01T08:30:00.000Z",
               "last_password_change": "2022-10-15T14:22:10.000Z",
               "credit_score": "720",
               "employer_information": {
               "annual_income": "",
               "employment_status": "employed",
               "employer_name": "Innovate Solutions",
               },
               "kyc_information": [
                  {
                  "id_number": "1234567890",
                  "id_type": "bvn",
                  "country": "NG",
                  },
                  {
                  "id_number": "1234567890",
                  "id_type": "NIN",
                  "country": "NG",
                  }
               ]
            },
      "transaction":{
               "id": "87554303-3f75-4883-8fb8-48fce003859f", //unique transaction id
               "time": "2022-12-12T12:15:05.391Z", //ISO 8601 format
               "amount": 8291,
               "currency": "XAF",
               "ref": "xaf",
               "session_id": "xaf",
               "type": "deposit",  //debit, credit, transfer, purchase, refund, withdrawal etc.
               "channel": "mobile",  //online, mobile, atm, branch, pos
               "purpose": "salary payment",  //bill payment, transfer, airtime, etc.
               "source_of_funds": "employment income"  //savings, business, investment, etc.
            },
      "payment":{
               "payment_id": "9931fac0-6bfa-4b3c-842c",
               "is_recurring": true, //true or false
               "method_type": "card", //card, ussd, transfer etc
               "scheme": "Visa",
               "card_funding": "debit", //credit or debit
               "card_last_four": "9876",
               "expiry_month": "10",
               "expiry_year": "25",
               "is_3ds_enabled": true,
               "is_card_present": true,
               "cvv_provided": true,
               "avs_passed": true,
               "name_on_card": "John Buchanan",
               "billing_address": {
               "city": "North Sarah",
               "street": "6238 Walker Unions Suite 802",
               "country": "Morocco"
               }
      },
      "merchant": {
               "name":"Merchant 1",
               "category":"Android",
               "country":"Nigeria"
      },
      "device":{
               "type":"mobile",
               "os":"Android",
               "model":"Pixel 7",
               "language":"en-US",
               "ip_address":"154.72.170.233",
               "device_id":"ff97adb7-8d3d-4f15-94df-87e21e1212de" //fingerprint_id
            },
         "address":{
               "address1": "6238 Walker Unions Suite 802",
               "address2": "",
               "city": "North Sarah",
               "region": "",
               "zipcode" : "23401",
               "country":"Morocco"
            }
   }
}

Onboarding

Request body

{
   "key": "<your_ingest_key>",
   "type":"onboarding",
   "event":{
         "user":{
                  "user_id":"9931fac0-6bfa-4b3c-842c-7840006d89b6",
                  "user_type": "individual",  //individual, business, government, other
                  "registration_time": "2022-12-12T12:15:05.392Z",
                  "email":"erik.miller@buchanan.com",
                  "name":"Trevor Arias",
                  "dob": "1980-01-01", //User's date of birth, YYYY-MM-DD format
                  "tier": "silver",  //basic, silver, gold, platinum
                  "account_type": "checking",  //savings, checking, business, student
                  "gender": "male",  //male, female, other
                  "balance": 24500.50,  //current account balance before transaction
                  "mobile":"5797454931",
                  "last_pin_change": "2022-11-01T08:30:00.000Z",
                  "last_password_change": "2022-10-15T14:22:10.000Z",
                  "credit_score": "720",
                  "employer_information": {
                  "annual_income": "",
                  "employment_status": "employed",
                  "employer_name": "Innovate Solutions",
                  },
                  "kyc_information": [
                     {
                     "id_number": "1234567890",
                     "id_type": "bvn",
                     "country": "NG",
                     },
                     {
                     "id_number": "1234567890",
                     "id_type": "NIN",
                     "country": "NG",
                     }
                  ]
               },
         "device":{
                  "type":"mobile",
                  "os":"Android",
                  "model":"Pixel 7",
                  "language":"en-US",
                  "ip_address":"154.72.170.233",
                  "device_id":"ff97adb7-8d3d-4f15-94df-87e21e1212de" //fingerprint_id
               },
         "address":{
                  "address1": "6238 Walker Unions Suite 802",
                  "address2": "",
                  "city": "North Sarah",
                  "region": "",
                  "zipcode" : "23401",
                  "country":"Morocco"
               }

      }

}

Webhook Notification Response

Response

{
    event: {
        meta: [
            {
                transaction_id: "Dojah-20231111085937073"
            }
        ],
        user: {
            name: "Maplerad-Provarex-Acc  None",
            email: "",
            mobile: "None",
            user_id: "4ac1bc59-34ad-485a-bda5-eb406a49a411",
            registration_time: "1696421468798421"
        },
        device: {
            os: "Android",
            type: "mobile",
            model: "Pixel 7",
            language: "en-US",
            device_id: "ff97adb7-8d3d-4f15-94df-87e21e1212de",
            ip_address: "154.72.170.233"
        },
        sender: {
            country: "NG",
            bank_name: "",
            account_name: "Paystack",
            account_number: "1017692813"
        },
        address: {
            city: "Lagos",
            street: "Ikeja",
            country: "Nigeria"
        },
        receiver: {
            country: "NG",
            bank_name: "VFD_NEW",
            account_name: "",
            account_number: "1029283851"
        },
        transaction: {
            id: "Dojah-20231111085937073",
            ref: "Dojah-20231111085937073",
            time: "1699693180085313",
            type: "deposit",
            amount: 300,
            channel: "transfer",
            currency: "NGN",
            session_id: "Dojah-20231111085937073"
        }
    },
    score: 30,
    decision: {
        action: "Allow",
        rule_status: false
    },
    behavioral: {
        UnusualTimeTransactions: {
            state: true,
            description: "User transaction time is outside of normal business hours"
        },
        AbnormalTransactionVolume: {
            state: true,
            description: "User has abnormally high transaction volume of 34 within a short period"
        }
    }
}

Documentation Index

​Request

​Real-time URL

​Backfill

​Headers

​Request Body Template

​Top-level Fields

​event.transaction

​event.user

​event.receiver

​event.sender

​event.payment

​event.merchant

​event.device

​event.address

​event.meta

​Transaction Monitoring - Use cases

​Banking

​Payments

​Onboarding

​Webhook Notification Response

Request

Real-time URL

Backfill

Headers

Request Body Template

Top-level Fields

event.transaction

event.user

event.receiver

event.sender

event.payment

event.merchant

event.device

event.address

event.meta

Transaction Monitoring - Use cases

Banking

Payments

Onboarding

Webhook Notification Response