Guide · Integrations and API
Connect your systems with the ioZen API
With the ioZen API your systems read your Intake Bots, submissions, contacts, cases and records, and send submissions to a bot. Create a key, pick its scopes and make your first call.
The ioZen API lets your own systems talk to ioZen. A clinic could pull its appointment Intake Bot's submissions every night, or a mechanic's workshop could send its bot the answers from a form it already has on its site.
1. Create a key
In the sidebar, go to “Integrations” and open the “API Keys” tab. Tap “Create API Key”.
Under “Name”, write something that tells you where it's used, like Appointments system. Under “Scopes”, check only what that key needs. Tap “Create API Key”.
2. Copy the key
ioZen shows you “Your API Key”. It starts with iozen_live_. Copy it now and keep it somewhere safe: you won't be able to see it again, because ioZen stores only a hash of it.
Each key gives access to one workspace: the one that created it.
3. Make your first call
Send the key in the Authorization header, after Bearer. This call lists your Intake Bots and needs the “Read Intake Bots” scope:
curl https://app.iozen.ai/api/v1/intake-bots \
-H "Authorization: Bearer iozen_live_YOUR_KEY"The response looks like this:
{
"success": true,
"data": {
"intake_bots": [],
"pagination": { "has_more": false, "next_cursor": null }
}
}When something goes wrong, you get "success": false with an error that holds a code and a message.
Scopes
| Scope | What it allows |
|---|---|
| “Read Intake Bots” | List your Intake Bots and read each one. |
| “Write Intake Bots” | Create submissions on an Intake Bot, for example with the answers from your own form. |
| “Read Submissions” | List an Intake Bot's submissions and read each one. |
| “Read Contacts” | List your contacts and read each one. |
| “Read Cases” | List your Process Boards and their cases. |
| “Read Records” | List your tables and their records. |
| “Manage Webhooks” | Create, edit, delete and test webhooks, see their deliveries and redeliver them. |
| “Send WhatsApp” | Open a WhatsApp conversation with an approved template and check a message's status. Needs the Business plan and a connected number: Connect WhatsApp. |
If a key calls something it has no scope for, the API answers 403.
Rate limits
Each key has a per-minute call limit that depends on your plan. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so you know how much you have left. Go over it and the API answers 429 with Retry-After: the seconds to wait.
Retry without duplicates using Idempotency-Key
If your system retries a POST, PATCH or PUT, send the Idempotency-Key header with a unique value, like a UUID. Repeat the call with the same key and the same body within 24 hours and ioZen returns the saved response without making the change twice, marked with X-Idempotent-Replayed: true. Same key with a different body, and the API answers 409.
Opening a WhatsApp conversation requires Idempotency-Key.
Revoke a key
If a key leaked or you no longer use it, open its menu and tap “Revoke”. On a phone, the button is on the key's card. Confirm with “Revoke Key”. Apps using it lose access right away.
The full reference
Every call, with its parameters and examples, is in the reference at app.iozen.ai/docs/api-reference. The “View API Documentation” link on the “API Keys” tab opens the same docs.
Frequently asked questions
- Which plan do I need for the API?
- Pro or higher. How many keys you can have depends on your plan; see Pricing.
- Can I see a key again?
- No. ioZen shows it once and stores only a hash. If you lose it, revoke it and create a new one.
- How many calls can I make?
- Each key has a per-minute limit that depends on your plan. Go over it and the API answers 429, with the Retry-After header telling you how many seconds to wait.
- Is the API reference available in Spanish?
- No. The reference is in English only, at app.iozen.ai/docs.