Why Use It?
Why the Integrations API?
Everything the Integrations API does ultimately writes to the same Avvyr platform as the Management API. You can call the Management API directly to create orders, update inventory, upsert products, and so on. So why route data through the Integrations API instead?
The short answer
The Management API is a synchronous CRUD interface. The Integrations API is a managed integration platform built on top of it. When you use the Integrations API, you get everything a scalable integration pipeline should offer — without building it yourself.
What the Integrations API adds
| Capability | Management API | Integrations API |
|---|---|---|
| Create / update data in Avvyr | ||
| Transaction tracking & status | Every request is tracked as an IntegrationEvent with full lifecycle (queued → processing → success | failed) | |
| Automatic retries | Exponential backoff with configurable retry counts per event type | |
| Manual resubmission | One-click retry from the dashboard or API | |
| Dead-letter handling | Failed events are captured and surfaced for investigation | |
| Communication logs | Full request/response logging with sensitive data masking | |
| Visual dashboard | See all transactions, filter by status, drill into details | |
| Event ordering (FIFO) | N/A | Service Bus sessions ensure per-integration ordering |
| Async processing | Synchronous request/response | Fire-and-forget with 202 Accepted — processing happens asynchronously |
When to use the Management API directly
The Management API is the right choice when you:
- Need synchronous responses — you want to know immediately if the operation succeeded
- Are building admin tools or dashboards that read and write data interactively
- Have a simple, low-volume integration where transaction tracking isn't worth the overhead
- Want full control over error handling and retry logic in your own code
- Already have your own integration platform with retry logic, dead-letter handling, monitoring, and logging — adding the Integrations API on top would duplicate those capabilities and introduce an extra layer of error handling to manage
When to use the Integrations API
The Integrations API is the right choice when you:
- Are building a production data pipeline (ERP sync, inventory feed, order import) where reliability matters
- Need visibility into what's flowing between systems without building your own monitoring
- Want automatic retries so transient failures don't cause data loss
- Have non-technical stakeholders who need to see integration status in a dashboard
- Are syncing data from a system that doesn't need immediate confirmation — async is fine
- Want to avoid building retry logic, dead-letter handling, logging, and monitoring yourself
A practical example
Scenario: Your ERP pushes inventory updates to Avvyr every 15 minutes.
With the Management API:
ERP → POST /v1/inventory/bulk-update → 200 OK (or 500 → you handle retry)
You get the data in, but if the call fails you need your own retry logic. No record of what was sent. No dashboard for ops to check.
With the Integrations API:
ERP → POST /integrations/custom/inbound → 202 Accepted
The platform handles the rest. Every update is tracked. Failures retry automatically. Your ops team can see exactly what's flowing in the dashboard. If something goes wrong at 2 AM, the event is waiting in failed status for someone to investigate and resubmit — not silently lost.
Summary
Think of the Management API as the engine and the Integrations API as the managed highway built on top of it. If you're just moving one thing once, drive direct. If you're running a continuous data pipeline, use the highway — it has guardrails, traffic monitoring, and breakdown recovery built in.