API versions and compatibility
The endpoint path and payload contract version are independent. POST /v1/telemetry/batches accepts supported payload versions. Use schema_version: 3 for new telemetry integrations.
V3 and V2
| Topic | V3 | V2 compatibility |
|---|---|---|
| Routing model | Reports the actual enabled destination and switch used. No Teria routing allocation required. | Validates against Teria's configured routes and routing allocation versions. |
| Minimum events | Standalone attempt outcomes are sufficient; receipt and start events are optional. | Retains the existing transaction and attempt lifecycle contract. |
| Event version field | Batch-level schema_version: 3 only. |
Batch and each event carry schema_version: 2. |
| Routing version field | routing_config_version is not accepted. |
Required for attempt events. |
| Reused event ID | Identical immutable content is a duplicate; different content is a conflict. | Existing event-ID deduplication behavior is retained. |
| Amount and currency | Both supplied together or both omitted. | Existing V2 field rules are retained. |
| Acceptance response | Request reference, batch ID, counts and acceptance time. | Existing acceptance response shape is retained. |
Both versions use institution-scoped credentials and the same batch endpoint. V3 keeps observations and attempt outcomes without claiming that outcomes-only telemetry proves a transaction's final state.
Existing V2 integrations can continue using their current contract. Changing schema_version alone is not a migration: review the field changes, routing assumptions and response handling, then verify your V3 integration in sandbox.
Download the V3 OpenAPI definition or the V2 compatibility definition. V1 remains a legacy contract for existing integrations and is outside this customer quickstart; contact Teria before changing an older integration.
Integration support
For directory changes, migration guidance or an integration issue, contact the Teria administrator who onboarded your institution. Include the environment and request reference when available; exclude credential secrets and personal data.