Polling
The recommended way to learn about new SDI outcomes and incoming invoices is webhooks. If you can't expose a public endpoint, for example because your integration is desktop software, you can query the API periodically: this page explains how to do it without missing events.
Two strategies
You can read new items in two ways, which can also be combined:
- with the
unreadfilter, which returns only items you haven't read yet; - with a time window, which returns items updated within a time range.
The unread filter
With unread=true you get only the items you haven't read yet. Reading them marks them as read, so they don't show up on the next call. What counts as reading depends on the endpoint:
| Endpoint | An item is marked as read when |
|---|---|
/update/ |
It appears in a response, in the list or the detail |
/receive/ |
You download its content: list or detail with include_payload=true, or /receive/{id}/payload |
Two practical consequences:
- Always request the first page. Read items drop out of the filter, so page 2 of the next call would skip items. Repeat the
page=1request until the response is empty. - Store items as soon as you receive them. Once returned they are already marked as read: if your processing stops halfway, you won't find them again with
unread=true. Use a time window to recover them.
A single reader
The unread filter assumes a single reader per account. If several processes read in parallel, each one gets only part of the items. In that case, use webhooks or a time window.
Time window
Alternatively, or as a reconciliation check, query the items updated within a range with last_update_from and last_update_to. To avoid missing anything:
- make windows overlap: for example, on each cycle also re-read the last few minutes of the previous one;
- deduplicate by
id: an item can appear in more than one window, but itsiddoesn't change.
Don't use the id as a cursor, that is, don't ask only for items with an id greater than the last one you saw: id values are assigned in ascending order, but they are not guaranteed to become visible in that order.
Frequency
SDI doesn't work in real time: between a send and its outcome there are usually minutes, sometimes hours. Reading every 30-60 minutes is more than enough. Polling endpoints have a dedicated limit of 180 requests per minute.
Costs
Reads are free, with one exception: the first download of a received invoice's content counts as a transaction. Later reads of the same invoice are free. See Pricing.
Everything is free in the Sandbox, but keep in mind that the simulator runs in hourly cycles and that received invoices are deleted every 24 hours.