> ## 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
> Push banking, payment, or onboarding events to Dojah EasyDetect and get a real-time Allow, Block, or Review verdict from rules, behaviour, and ML.
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](/api-reference/easydetect/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](/dashboard-guide/fraud-risk/easydetect/events) 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.
```json Banking theme={null}
{
"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" }
]
}
}
```
```json Payments theme={null}
{
"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"
}
}
}
```
```json Onboarding theme={null}
{
"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](/api-reference/core-concepts/webhooks-signatures) — 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. |
```bash cURL theme={null}
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"
}
}
}'
```
```js Node.js theme={null}
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();
```
```python Python theme={null}
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()
```
```json POST /api/ingest theme={null}
{
"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"
}
}
}
```