> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dojah.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send Events for Fraud Monitoring

> Push banking, payment, or onboarding events to EasyDetect. Get real-time Allow, Block, or Review verdicts via API.

### Request

#### Real-time URL

```http [POST] theme={null}
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

```http [POST] theme={null}
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](/dashboard-guide/fraud-and-risk/easydetect/events).

<Warning>
  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.
</Warning>

### 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

```json Request body theme={null}
{
   "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

```json Request body theme={null}
{
   "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

```json Request body theme={null}
{
   "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

```json Response theme={null}
{
    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"
        }
    }
}
```