# 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.

> **Before you start:** You need the Pro plan, and you must be the workspace owner or an admin.

## 1. Create a key

In the sidebar, go to “Integrations” and open the “API Keys” tab. Tap **“Create API Key”**.

![The API keys tab, before you create the first one.](https://iozen.ai/docs/shots/en/api-keys-desktop.webp)

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:

```bash
curl https://app.iozen.ai/api/v1/intake-bots \
  -H "Authorization: Bearer iozen_live_YOUR_KEY"
```

The response looks like this:

```json
{
  "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](https://iozen.ai/docs/iozen-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](https://iozen.ai/docs/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](https://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.