Send Events

curl --request POST \
  "https://ingest.dojah.io/api/ingest" \
  -H "Authorization: {{secret_key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "{{ingest_key}}",
    "type": "banking",
    "event": {
      "transaction": {
        "id": "87554303-3f75-4883",
        "time": "2022-12-12T12:15:05.391Z",
        "amount": 8291,
        "currency": "NGN",
        "type": "transfer",
        "channel": "mobile"
      },
      "user": {
        "user_id": "9931fac0-6bfa-4b3c",
        "registration_time": "2022-12-12T12:15:05.392Z",
        "email": "erik.miller@buchanan.com",
        "name": "Trevor Arias"
      },
      "device": {
        "ip_address": "154.72.170.233",
        "device_id": "ff97adb7-8d3d-4f15"
      }
    }
  }'

const res = await fetch("https://ingest.dojah.io/api/ingest", {
  method: "POST",
  headers: {
    Authorization: process.env.DOJAH_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    key: process.env.DOJAH_INGEST_KEY,
    type: "banking",
    event: {
      transaction: {
        id: "87554303-3f75-4883",
        time: "2022-12-12T12:15:05.391Z",
        amount: 8291,
        currency: "NGN",
        type: "transfer",
        channel: "mobile",
      },
      user: {
        user_id: "9931fac0-6bfa-4b3c",
        registration_time: "2022-12-12T12:15:05.392Z",
        email: "erik.miller@buchanan.com",
        name: "Trevor Arias",
      },
      device: {
        ip_address: "154.72.170.233",
        device_id: "ff97adb7-8d3d-4f15",
      },
    },
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://ingest.dojah.io/api/ingest",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "key": os.environ["DOJAH_INGEST_KEY"],
        "type": "banking",
        "event": {
            "transaction": {
                "id": "87554303-3f75-4883",
                "time": "2022-12-12T12:15:05.391Z",
                "amount": 8291,
                "currency": "NGN",
                "type": "transfer",
                "channel": "mobile",
            },
            "user": {
                "user_id": "9931fac0-6bfa-4b3c",
                "registration_time": "2022-12-12T12:15:05.392Z",
                "email": "erik.miller@buchanan.com",
                "name": "Trevor Arias",
            },
            "device": {
                "ip_address": "154.72.170.233",
                "device_id": "ff97adb7-8d3d-4f15",
            },
        },
    },
)
data = res.json()

{
  "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 within a short period"
    }
  },
  "event": {
    "transaction": {
      "id": "Dojah-20231111085937073",
      "amount": 300,
      "currency": "NGN",
      "type": "deposit"
    },
    "user": {
      "user_id": "4ac1bc59-34ad-485a",
      "name": "Maplerad-Provarex-Acc"
    }
  }
}

POST/api/ingest

Push banking, payment, or onboarding events to EasyDetect as they happen and get a real-time Allow, Block, or Review verdict. Dojah scores each event against your rules, behavioural signals, and ML in milliseconds.

Base URL

EasyDetect exposes a dedicated ingest host. Send new events to the real-time endpoint; upload historical data with Backfill Events.

Purpose	Method	URL
Real-time events	POST	`https://ingest.dojah.io/api/ingest`
Historical backfill	POST	`https://ingest.dojah.io/api/ingest/backfill`

Headers

Header	Required	Description
`Authorization`	Yes	Your private/secret key, sent as-is — not `Bearer`.
`Content-Type`	Yes	`application/json`.

Request body

Every request carries three top-level fields. The event object holds the nested objects below — include as many as apply to your event type for more accurate scoring. Fields marked required must be present; the rest are optional but recommended.

The key in the request body is your Ingest key, which is not the same as the secret key you send in the Authorization header. Find your Ingest key in EasyDetect settings on your dashboard, and see Connect a Flow for where it lives.

Top-level fields

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

event.transaction — banking, payments

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

event.user — all types

Field	Type	Required	Description
`user_id`	string	No	Unique user identifier.
`user_type`	string	No	`individual`, `business`, `government`, `other`.
`registration_time`	string	Yes	Registration timestamp, ISO 8601.
`email`	string	No	User email address.
`name`	string	No	User full name.
`dob`	string	No	Date of birth, `YYYY-MM-DD` (payments, onboarding).
`tier`	string	No	`basic`, `silver`, `gold`, `platinum`.
`account_type`	string	No	`savings`, `checking`, `business`, `student`.
`gender`	string	No	`male`, `female`, `other`.
`balance`	number	No	Account balance before the transaction.
`mobile`	string	No	User phone number.
`last_pin_change`	string	No	Last PIN change, ISO 8601.
`last_password_change`	string	No	Last password change, ISO 8601.
`credit_score`	string	No	User credit score (payments, onboarding).
`employer_information`	object	No	`annual_income`, `employment_status`, `employer_name`.
`kyc_information`	array	No	KYC documents, each with `id_number`, `id_type`, `country`.

Other event objects

Object	Applies to	Key fields
`event.receiver`	banking	`account_name`, `bank_name`, `account_number`, `country`.
`event.sender`	banking	`account_name`, `bank_name`, `account_number`, `country`.
`event.payment`	payments	`payment_id`, `is_recurring`, `method_type`, `scheme`, `card_funding`, `card_last_four`, `expiry_month`, `expiry_year`, `is_3ds_enabled`, `is_card_present`, `cvv_provided`, `avs_passed`, `name_on_card`, `billing_address`.
`event.merchant`	payments	`name`, `category`, `country`.
`event.device`	all types	`type`, `os`, `model`, `language`, `ip_address`, `device_id`.
`event.address`	all types	`city`, `street`, `address1`, `address2`, `region`, `zipcode`, `country`.
`event.meta`	banking	Array of custom `key`/`value` objects for additional context.

Request body templates

Each event type expects a different combination of the objects above. Start from the template that matches your use case and drop any field you don’t collect — only key, type, event.transaction.time (banking and payments), and event.user.registration_time are required.

{
  "key": "{{ingest_key}}",
  "type": "banking",
  "event": {
    "transaction": {
      "id": "87554303-3f75-4883-8fb8-48fce003859f",
      "time": "2022-12-12T12:15:05.391Z",
      "amount": 8291,
      "currency": "NGN",
      "ref": "xaf",
      "session_id": "xaf",
      "type": "deposit",
      "channel": "mobile",
      "purpose": "salary payment",
      "source_of_funds": "employment income"
    },
    "user": {
      "user_id": "9931fac0-6bfa-4b3c-842c-7840006d89b6",
      "user_type": "individual",
      "registration_time": "2022-12-12T12:15:05.392Z",
      "email": "erik.miller@buchanan.com",
      "name": "Trevor Arias",
      "tier": "silver",
      "account_type": "checking",
      "gender": "male",
      "balance": 24500.5,
      "mobile": "5797454931",
      "last_pin_change": "2022-11-01T08:30:00.000Z",
      "last_password_change": "2022-10-15T14:22:10.000Z"
    },
    "sender": {
      "account_name": "Anon Doe",
      "bank_name": "Paystack TITAN",
      "account_number": "NG0567890321",
      "country": "Nigeria"
    },
    "receiver": {
      "account_name": "John Doe",
      "bank_name": "EcoBank",
      "account_number": "CM21100375689",
      "country": "Cameroon"
    },
    "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" }
    ]
  }
}

{
  "key": "{{ingest_key}}",
  "type": "payments",
  "event": {
    "transaction": {
      "id": "87554303-3f75-4883-8fb8-48fce003859f",
      "time": "2022-12-12T12:15:05.391Z",
      "amount": 8291,
      "currency": "NGN",
      "ref": "xaf",
      "session_id": "xaf",
      "type": "purchase",
      "channel": "online",
      "purpose": "bill payment",
      "source_of_funds": "employment income"
    },
    "user": {
      "user_id": "9931fac0-6bfa-4b3c-842c-7840006d89b6",
      "user_type": "individual",
      "registration_time": "2022-12-12T12:15:05.392Z",
      "email": "erik.miller@buchanan.com",
      "name": "Trevor Arias",
      "dob": "1980-01-01",
      "tier": "silver",
      "account_type": "checking",
      "gender": "male",
      "balance": 24500.5,
      "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": "4500000",
        "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"
        }
      ]
    },
    "payment": {
      "payment_id": "9931fac0-6bfa-4b3c-842c",
      "is_recurring": true,
      "method_type": "card",
      "scheme": "Visa",
      "card_funding": "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": "electronics",
      "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": {
      "address1": "6238 Walker Unions Suite 802",
      "address2": "",
      "city": "North Sarah",
      "region": "",
      "zipcode": "23401",
      "country": "Morocco"
    }
  }
}

{
  "key": "{{ingest_key}}",
  "type": "onboarding",
  "event": {
    "user": {
      "user_id": "9931fac0-6bfa-4b3c-842c-7840006d89b6",
      "user_type": "individual",
      "registration_time": "2022-12-12T12:15:05.392Z",
      "email": "erik.miller@buchanan.com",
      "name": "Trevor Arias",
      "dob": "1980-01-01",
      "tier": "silver",
      "account_type": "checking",
      "gender": "male",
      "balance": 24500.5,
      "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": "4500000",
        "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"
    },
    "address": {
      "address1": "6238 Walker Unions Suite 802",
      "address2": "",
      "city": "North Sarah",
      "region": "",
      "zipcode": "23401",
      "country": "Morocco"
    }
  }
}

Response

Dojah scores the event and delivers the result to your webhook — an overall score, a decision.action of Allow, Block, or Review, and the behavioral signals that fired (with a description of each). The original event is echoed back for context.

Errors

Code	Meaning
`400`	Bad request — `type` is invalid or a required field is missing.
`401`	Unauthorized — check your `Authorization` key (no `Bearer` prefix) and body `key`.
`422`	Unprocessable — the event payload failed validation.
`429`	Too many requests — back off and retry.

curl --request POST \
  "https://ingest.dojah.io/api/ingest" \
  -H "Authorization: {{secret_key}}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "{{ingest_key}}",
    "type": "banking",
    "event": {
      "transaction": {
        "id": "87554303-3f75-4883",
        "time": "2022-12-12T12:15:05.391Z",
        "amount": 8291,
        "currency": "NGN",
        "type": "transfer",
        "channel": "mobile"
      },
      "user": {
        "user_id": "9931fac0-6bfa-4b3c",
        "registration_time": "2022-12-12T12:15:05.392Z",
        "email": "erik.miller@buchanan.com",
        "name": "Trevor Arias"
      },
      "device": {
        "ip_address": "154.72.170.233",
        "device_id": "ff97adb7-8d3d-4f15"
      }
    }
  }'

const res = await fetch("https://ingest.dojah.io/api/ingest", {
  method: "POST",
  headers: {
    Authorization: process.env.DOJAH_SECRET_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    key: process.env.DOJAH_INGEST_KEY,
    type: "banking",
    event: {
      transaction: {
        id: "87554303-3f75-4883",
        time: "2022-12-12T12:15:05.391Z",
        amount: 8291,
        currency: "NGN",
        type: "transfer",
        channel: "mobile",
      },
      user: {
        user_id: "9931fac0-6bfa-4b3c",
        registration_time: "2022-12-12T12:15:05.392Z",
        email: "erik.miller@buchanan.com",
        name: "Trevor Arias",
      },
      device: {
        ip_address: "154.72.170.233",
        device_id: "ff97adb7-8d3d-4f15",
      },
    },
  }),
});
const data = await res.json();

import os, requests

res = requests.post(
    "https://ingest.dojah.io/api/ingest",
    headers={
        "Authorization": os.environ["DOJAH_SECRET_KEY"],
        "Content-Type": "application/json",
    },
    json={
        "key": os.environ["DOJAH_INGEST_KEY"],
        "type": "banking",
        "event": {
            "transaction": {
                "id": "87554303-3f75-4883",
                "time": "2022-12-12T12:15:05.391Z",
                "amount": 8291,
                "currency": "NGN",
                "type": "transfer",
                "channel": "mobile",
            },
            "user": {
                "user_id": "9931fac0-6bfa-4b3c",
                "registration_time": "2022-12-12T12:15:05.392Z",
                "email": "erik.miller@buchanan.com",
                "name": "Trevor Arias",
            },
            "device": {
                "ip_address": "154.72.170.233",
                "device_id": "ff97adb7-8d3d-4f15",
            },
        },
    },
)
data = res.json()

{
  "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 within a short period"
    }
  },
  "event": {
    "transaction": {
      "id": "Dojah-20231111085937073",
      "amount": 300,
      "currency": "NGN",
      "type": "deposit"
    },
    "user": {
      "user_id": "4ac1bc59-34ad-485a",
      "name": "Maplerad-Provarex-Acc"
    }
  }
}

Get started

Core concepts

API Endpoints

Widget SDKs

API clients

Base URL

Headers

Request body

Top-level fields

event.transaction — banking, payments

event.user — all types

Other event objects

Request body templates

Response

Errors

​Base URL

​Headers

​Request body

​Top-level fields

​event.transaction — banking, payments

​event.user — all types

​Other event objects

​Request body templates

​Response

​Errors

Base URL

Headers

Request body

Top-level fields

event.transaction — banking, payments

event.user — all types

Other event objects

Request body templates

Response

Errors