Skip to main content
Use POST /v2/events to send monitoring events from a provider, wallet, ledger, or internal system.

​
When to use it

Use this endpoint when you have a new fact about a monitored money movement. Send the event as soon as the source system records it.

​
Request shapes

Each event has flow, type, reference, and entity_id. The target type is derived from the flow. Use id for retry-safe delivery. Add occurred_at, amount, currency, and provider-specific data when available. Send one event as a JSON object or send several events as a bare JSON array. The existing { "events": [...] } wrapper remains supported for compatibility.
An array contains one to 500 event objects. Reconify returns one result for each input index.
​
string
Stable event identity. Use it when a sender can retry a request.
​
string
Opaque cross-service identifier, 1 to 200 visible ASCII characters. It links evidence for investigation and does not change operation grouping.
​
string
Opaque identifier of the single earlier event that led to this event, 1 to 200 visible ASCII characters. The value is not resolved at ingest.
​
string
required
accepted, duplicate, or rejected for the corresponding event.
The generated POST /v2/events reference owns exact schema rules and examples. The integration guide explains how to send and retry events.
  • flow, type, reference, and entity_id are required.
  • The request body can be one event object, an array of one to 500 events, or the existing { "events": [...] } wrapper.
  • amount and currency are required for event types that carry a monetary amount.
  • payment.failed and payout.failed do not require an amount.
  • Payment → Wallet, Wallet → Wallet, and Wallet → Payout use wallet targets. Payment → Order uses order targets.
  • Use an id that matches ^evt_[0-9A-Z]{26}$ when you need retry protection.
  • correlation_id is optional. When present it must be 1 to 200 visible ASCII characters; null, empty, and whitespace-padded values are rejected.
  • causation_id follows the same length and character rules. It may name an event Reconify has not received.

​
Batch behavior

  • Send 1–500 events per request.
  • Reconify validates each event independently.
  • Results use the input index.
  • 202 means at least one item was accepted or duplicated.
  • 422 means every item was rejected.

​
Per-event retry identity

event.id protects one event inside a batch. Retry with the same ID and payload to receive duplicate. Reusing the ID with different content returns idempotency_conflict for that item. Events without IDs receive generated IDs. A retry can create another event. Add IDs before using retries in production.