Waits for the events of one correlation — the long poll behind interactive registration — and returns the correlation's summary.

Pass the correlation_id returned by POST /v3/erp/updates/events and say what you are waiting for:

• wait_for_entities — entity slugs, optionally with a selector: contact, contract[billing_account_number=4711].
• wait_for_use_cases — inbound use case slugs: contract, meter_reading. A meter reading is not an entity, so this is how a wait names one.

The call returns as soon as completion is decided, or after wait seconds. completion is one of:

• requirements_met — every listed requirement is satisfied. This wins even if an unrelated event of the correlation failed; errors still lists it.
• complete — the partner closed the correlation (correlation_complete) and every event it sent has finished. Nothing further can arrive, so the wait ends even if a requirement is unmet. A correlation closed with zero events is complete at once: the partner sent nothing and never will. complete is final. From completed_at on, the correlation's answer is frozen: an event that still arrives under it (a late event) is processed and counted in events_received, events_done and late_events, and its errors are listed with after_completion: true, but it adds nothing to use_cases or entities and never changes completion — every later read gives the answer the first one got.
• error — a requirement can no longer be met because an event it depends on failed: every event of a required use case ended in error, or an entity requirement is still missing when the correlation is complete and one of its events failed. Without requirements, error means the correlation completed with failures. An event that ended partial counts as failed here: a use case requirement is met only by an event that ended done.
• timeout — the budget ran out first. The body still shows what has landed so far; call again to keep waiting.

When entities_omitted is present, an entity requirement can be undecided. entities lists at most 200 entity writes; the rest are only counted. An entity requirement that no listed entity satisfies may then still have been written, so it is neither met nor missing: it is named in undecided_entity_requirements, it never makes completion error, and the wait still ends complete once the correlation completes (if every other requirement is met, complete rather than requirements_met). Look such an entity up yourself, e.g. by its unique id through the entity API. Use case requirements are never undecided: their counts are never omitted.

Every requirement is met by the first matching event. A use case requirement is satisfied by the first event of that use case to finish, and an entity requirement without a selector by the first entity of that slug; neither says anything about the rest. So, unless the partner sends correlation_complete, requirements_met does not mean the partner has finished: more data for the same customer may still be arriving. correlation_complete is the only signal that nothing further is coming — strongly recommended for every partner, never required. When you know the identifier you are waiting for, an entity requirement with a selector is the precise tool: contract[billing_account_number=4711] is satisfied by that contract and by nothing else.

An event fails when nothing will retry what went wrong, including when its mapping could not run or ran only in part: a disabled or unconfigured use case, an item without its unique identifiers, a field or relation that could not be mapped. Such an event ends error when it wrote nothing and partial when it wrote something, and errors says why. A mapping that writes nothing on purpose (an enabled expression that is false, an empty list) ends done.

A requirement is only as good as the use case configuration it refers to: model one inbound use case per partner event type, and give every use case a slug. A legacy use case without a slug is counted, and can be named, only by its use case id, which differs between environments.

An unknown correlation, or one with no interactive events, reads as events_received: 0, closed: false — "not yet" and "never" look the same, which is why correlation_complete exists. Waiting on a correlation before anything was sent under it is normal — mint the id, hand it to the partner, wait — and the wait picks the correlation up as soon as its first event is ingested.

A correlation belongs to one integration: the one whose event (or close) created it. Events and closes of another integration under the same id are not applied to it — see correlation_complete and the event results.

Waiting holds a connection, so concurrent waits are capped per organization and overall. A wait that starts before anything was sent under its correlation counts against a separate, smaller per-organization cap instead, for its whole duration, so waits on ids nothing is ever sent under cannot crowd out waits on correlations that exist. Over a cap the call is refused with 429 and Retry-After; fall back to calls with wait=0 (they never need a slot) or retry later. Calls that do not have to wait — wait=0, or a correlation that is already decided — are never refused.

Requires integration:view on the correlation's integration. The organization is always the token's own, so no other organization's correlation is ever visible.

{
  "entities": [
    {
      "slug": "contact",
      "unique_ids": {
        "reenumber": "4711"
      }
    }
  ],
  "undecided_entity_requirements": [
    "contract[billing_account_number=4711]"
  ]
}