Submit monitoring events

curl --request POST \
  --url https://api.reconifyhq.com/v2/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "amount": "150.00",
    "currency": "USD",
    "data": {
      "provider": "stripe",
      "provider_reference": "pi_123"
    },
    "entity_id": "wallet_123",
    "flow": "payment_to_wallet",
    "id": "evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9",
    "occurred_at": "2026-01-01T00:00:00Z",
    "reference": "order-123",
    "type": "payment.succeeded"
  },
  {
    "data": {
      "failure_code": "card_declined",
      "failure_message": "The card was declined.",
      "provider": "stripe",
      "provider_reference": "pi_124",
      "retryable": false
    },
    "entity_id": "wallet_123",
    "flow": "payment_to_wallet",
    "id": "evt_01J3Y0M8VJQ5W1R3E4J4K7N8Q0",
    "occurred_at": "2026-01-01T00:00:00Z",
    "reference": "order-124",
    "type": "payment.failed"
  }
]
'

{
  "results": [
    {
      "event_id": "evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9",
      "index": 0,
      "status": "accepted"
    }
  ]
}

{
  "code": "malformed_request",
  "message": "request body must be a JSON object or array"
}

{
  "code": "unauthorized",
  "message": "authentication required"
}

{
  "code": "forbidden",
  "message": "wallet integrity monitoring is not enabled"
}

{
  "code": "request_too_large",
  "message": "request exceeds the 5 MiB limit"
}

{
  "results": [
    {
      "code": "invalid_event",
      "field": "amount",
      "index": 0,
      "message": "amount is required for this event type",
      "status": "rejected"
    }
  ]
}

{
  "code": "database_unavailable",
  "message": "monitoring ingestion is unavailable"
}

POST

https://api.reconifyhq.com

events

curl --request POST \
  --url https://api.reconifyhq.com/v2/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
[
  {
    "amount": "150.00",
    "currency": "USD",
    "data": {
      "provider": "stripe",
      "provider_reference": "pi_123"
    },
    "entity_id": "wallet_123",
    "flow": "payment_to_wallet",
    "id": "evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9",
    "occurred_at": "2026-01-01T00:00:00Z",
    "reference": "order-123",
    "type": "payment.succeeded"
  },
  {
    "data": {
      "failure_code": "card_declined",
      "failure_message": "The card was declined.",
      "provider": "stripe",
      "provider_reference": "pi_124",
      "retryable": false
    },
    "entity_id": "wallet_123",
    "flow": "payment_to_wallet",
    "id": "evt_01J3Y0M8VJQ5W1R3E4J4K7N8Q0",
    "occurred_at": "2026-01-01T00:00:00Z",
    "reference": "order-124",
    "type": "payment.failed"
  }
]
'

{
  "results": [
    {
      "event_id": "evt_01J3Y0M8VJQ5W1R3E4J4K7N8P9",
      "index": 0,
      "status": "accepted"
    }
  ]
}

{
  "code": "malformed_request",
  "message": "request body must be a JSON object or array"
}

{
  "code": "unauthorized",
  "message": "authentication required"
}

{
  "code": "forbidden",
  "message": "wallet integrity monitoring is not enabled"
}

{
  "code": "request_too_large",
  "message": "request exceeds the 5 MiB limit"
}

{
  "results": [
    {
      "code": "invalid_event",
      "field": "amount",
      "index": 0,
      "message": "amount is required for this event type",
      "status": "rejected"
    }
  ]
}

{
  "code": "database_unavailable",
  "message": "monitoring ingestion is unavailable"
}

Authorizations

Authorization

string

header

required

Organization API key. Use a write-scoped key for event ingestion.

Body

application/json

Option 1 · object
Option 2 · object[]
Option 3 · object

Submit one event, a bare array of events, or the backward-compatible events wrapper.

entity_id

string

required

Target identifier. Its entity type is derived from the selected flow.

Minimum string length: 1

flow

enum<string>

required

Monitoring flow that defines the expected evidence sequence.

Available options:

payment_to_wallet,

payment_to_order,

wallet_to_wallet,

wallet_to_payout,

provider_to_settlement_account

reference

string

required

Stable local business reference supplied by the producer.

Minimum string length: 1

type

enum<string>

required

Lifecycle event type, such as payment.succeeded.

Available options:

order.fulfilled,

payment.failed,

payment.initiated,

payment.succeeded,

payout.failed,

payout.initiated,

payout.succeeded,

settlement.allocations_recorded,

settlement.created,

settlement.disbursed,

settlement.failed,

settlement.finalized,

settlement.received,

settlement.revised,

wallet.credited,

wallet.debited,

wallet.refunded

amount

string

Decimal amount in the event currency.

Pattern: ^(0|[1-9][0-9]*)(\.[0-9]+)?$

causation_id

string

Optional opaque identifier for the single earlier event that caused this event. It is not resolved at ingest.

Required string length: 1 - 200

Pattern: ^[\x21-\x7E]+$

correlation_id

string

Optional producer-supplied opaque identifier propagated across services. Do not include secrets or personal data.

Required string length: 1 - 200

Pattern: ^[\x21-\x7E]+$

currency

string

Three-letter uppercase ISO currency code.

Pattern: ^[A-Z]{3}$

data

object

Optional provider, failure, or retry context.

Show child attributes

financial_breakdown

object

Show child attributes

string

Optional stable ULID used to identify the event across retries.

Pattern: ^evt_[0-9A-Z]{26}$

metadata

object

Optional flat key-value context retained with the event.

Show child attributes

occurred_at

string<date-time>

Time when the event occurred in the source system.

Response

Accepted

results

object[]

required

Results in the same order as the submitted events.

Show child attributes

Start here

Event ingestion

Event reads

Issue operations

Organization

Authorizations

Body

Response