Staying in sync

Ele does not send webhooks or other notifications to your server yet. To learn that something changed, you poll: call a read operation again, compare the result with what you stored, and act on the difference.

Each call reads one organization. If your staff look after many organizations, poll each one, and spread the calls over time rather than sending them all at once.

What to poll

To follow	Call	How often
A payment you created	getPayment	Every 30–60 seconds while it is in progress
Approvals waiting for a person	listApprovals	Every minute or two while someone is using your product
Everything that needs a person	listAttentionItems	Every minute or two while someone is using your product
New and changed transactions	listTransactions	Every few minutes
Balances	getOrganizationBalance	Every few minutes, and after a new transaction
Onboarding	getOrganizationCapabilities	When a person opens onboarding, then every few minutes while a review is under way

These intervals are suggestions. Poll less often when nobody is looking, and never poll faster than you need.

Payments

A new payment starts as awaiting_approval. Poll getPayment until its status is one of succeeded, failed, cancelled or reversed.

failed, cancelled and reversed are final. succeeded is not quite: a payment can still be reversed afterwards, for example when the receiving bank returns a transfer. After a payment succeeds, check it again now and then, for example once a day for a few days.

While it is awaiting_approval, nothing happens until a person approves or rejects it, which can take hours. Poll slowly in that state, every few minutes, and faster once it has moved on to submitted or processing.

The payment’s rail says how the money travels: fiat for a bank transfer, crypto for a transfer on a blockchain, or ele_id for a transfer between two Ele accounts.

Approvals

listApprovals returns the pending approval requests by default, with pending_count beside the page. Compare the IDs with your last poll to find new ones. To find out what happened to a request that has left the list, fetch it with getApproval.

What needs a person

listAttentionItems is one feed of everything in an organization that is waiting for someone to act. Blocking items come first, then the earliest deadlines. Each item says whether the person whose token you use can act on it (actionable_by_viewer), and its action says what to do.

Today the feed covers approval requests waiting for review, and incoming crypto deposits that need details about the sender. Ele will add more kinds of item, so handle a kind you do not know.

For a badge or a count, call getAttentionSummary. It returns exact counts without the items.

Transactions

listTransactions returns the newest transactions first. To find new ones, read pages from the start until you reach a transaction you already have.

A transaction can change after it first appears: a pending card payment settles, or a transfer completes. To catch these changes, re-read the last few days on each poll, using date_start, and update what you stored. See Pagination for reading page by page.

Onboarding

Identity and business checks take time, sometimes days. While they are under way, poll getOrganizationCapabilities every few minutes when someone is waiting on the result, and a few times a day otherwise. For a person’s own checks, use getViewerCapabilities.