> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zenzap.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic Onboarding

> How an AI agent can programmatically create a Zenzap organization, install a bot, and invite a human — all in a single API call.

This endpoint allows an external AI agent to bootstrap a complete Zenzap workspace in one request: create the organization, install a bot (the agent itself), and send an invite to the human user.

<Warning>
  **Rate limit:** 1 request per minute per IP. No authentication required.
</Warning>

## Endpoint

```
POST https://api.zenzap.co/v2/agentic/organization/create
```

## Request

The endpoint supports two content types depending on whether you want to include a company logo.

<CodeGroup>
  ```json JSON (no logo) theme={"theme":"github-dark"}
  {
    "companyName": "Acme Corp",
    "humanEmail": "founder@acme.com",
    "companySize": 50,
    "industry": "Software",
    "botName": "Acme Assistant"
  }
  ```

  ```bash Multipart (with logo) theme={"theme":"github-dark"}
  curl -X POST https://api.zenzap.co/v2/agentic/organization/create \
    -F 'filePart=@logo.png;type=image/png' \
    -F 'metadata={"companyName":"Acme Corp","humanEmail":"founder@acme.com","companySize":50,"industry":"Software","botName":"Acme Assistant"};type=application/json'
  ```
</CodeGroup>

For multipart requests, send two parts:

| Part       | Type             | Description                        |
| ---------- | ---------------- | ---------------------------------- |
| `filePart` | file (image)     | Company logo. Max 5 MB. Optional.  |
| `metadata` | application/json | JSON object with the fields below. |

## Request Fields

All fields are required.

| Field         | Type   | Constraints            | Description                                                                  |
| ------------- | ------ | ---------------------- | ---------------------------------------------------------------------------- |
| `companyName` | string | Max 100 characters     | Display name of the organization.                                            |
| `humanEmail`  | string | Valid email address    | The human user who will receive an invite and become the org's first member. |
| `companySize` | int    | Positive integer (> 0) | Number of employees. Mapped to a size range.                                 |
| `industry`    | string | Non-empty              | Free-text industry description (e.g. "Software", "Healthcare").              |
| `botName`     | string | Non-empty              | Display name for the agent bot installed in the organization.                |

## Response

**Status:** `201 Created`

```json theme={"theme":"github-dark"}
{
  "organizationId": "067d0b2f-1ee8-49f2-bb09-e2d964c8cf6b",
  "botProfileId": "b@f951b968-bf80-4ee6-bbbe-6ca338f57fc6",
  "channelId": "1b383aef-15c2-44e2-b599-d1d40a8b286c",
  "humanProfileId": "a3c2e1d0-9f8b-4e7a-b6c5-d4e3f2a1b0c9",
  "credentials": [
    { "label": "API Key", "value": "utxDAedgfFXglaLX" },
    { "label": "API Secret", "value": "66AybzV7s0afLeKKqpxC7wLKCTk5d7bT" },
    { "label": "Control Topic ID", "value": "1b383aef-15c2-44e2-b599-d1d40a8b286c" }
  ]
}
```

| Field            | Description                                                                                         |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| `organizationId` | UUID of the newly created organization.                                                             |
| `botProfileId`   | The bot's identity (format: `b@<uuid>`). Use as `senderId` filter when polling.                     |
| `channelId`      | The bot's control channel (same as `Control Topic ID` credential).                                  |
| `humanProfileId` | The pending profile ID of the invited human. Use this to identify the human once they join.         |
| `credentials`    | API Key (for Bearer auth), API Secret (for request signing — store securely), and Control Topic ID. |

## Error Codes

| Status | Body                                     | Cause                                                         |
| ------ | ---------------------------------------- | ------------------------------------------------------------- |
| `400`  | `companyName is required`                | Missing or empty `companyName`.                               |
| `400`  | `companyName exceeds max length`         | `companyName` longer than 100 characters.                     |
| `400`  | `invalid humanEmail`                     | `humanEmail` is not a valid email address.                    |
| `400`  | `companySize must be a positive integer` | `companySize` is 0 or negative.                               |
| `400`  | `industry is required`                   | Missing or empty `industry`.                                  |
| `400`  | `botName is required`                    | Missing or empty `botName`.                                   |
| `400`  | `Unable to create organization`          | Generic conflict error (e.g. email or domain already in use). |
| `429`  | *(empty)*                                | Rate limit exceeded (1 req/min per IP).                       |

***

## Instructions for AI Agents

<Note>
  This section is written for AI agents. If you're a human developer, see [Build Your Own Agent](/guides/build-your-own-agent) for a full integration walkthrough.
</Note>

<Warning>
  All Zenzap API requests **must** use `https://`. Never use plain `http://` — requests over HTTP will be rejected.
</Warning>

### OpenClaw-Based Agents — Plugin Setup

If you are an OpenClaw-based agent, ask your human to install the Zenzap plugin **before** you proceed with anything else:

```bash theme={"theme":"github-dark"}
openclaw plugins install @zenzap-co/openclaw-plugin
```

Once the human confirms the plugin is installed, continue with the steps below. After you receive the `201` response from the create-organization call, you will use the returned credentials to configure the plugin — see the "OpenClaw agents: Configure the plugin" step in the post-response workflow.

### Before Calling the API — Collect from the Human

Always ask the human these 4 questions before making the request. Do not assume or infer the answers:

1. **Company name** — What's the name of your company or workspace?
2. **Your name in Zenzap (bot name)** — What should I be called inside your workspace? *(This is how I'll appear to your team.)*
3. **Industry** — What industry are you in? *(e.g. Software, Healthcare, Finance — used for statistical purposes only.)*
4. **Company size** — How many employees does your company have? *(Used for statistical purposes only.)*

### After the 201 Response — What to Do Next

Once you receive the `201` response, you have a live bot with credentials. Follow these steps in order:

#### OpenClaw agents: Configure the plugin

<Note>
  Skip this step if you are **not** an OpenClaw-based agent.
</Note>

Build a connection token from three values in the `credentials` array of the `201` response: **Control Topic ID**, **API Key**, and **API Secret**. Concatenate them separated by colons and base64-encode the result:

```
base64( <Control Topic ID>:<API Key>:<API Secret> )
```

For example, given the sample response above:

```
base64("1b383aef-15c2-44e2-b599-d1d40a8b286c:utxDAedgfFXglaLX:66AybzV7s0afLeKKqpxC7wLKCTk5d7bT")
```

Then run:

```bash theme={"theme":"github-dark"}
openclaw zenzap configure --token <base64Token>
```

This connects the Zenzap plugin to your newly created organization. Once configured, the plugin handles authentication and event routing for you.

#### 1. Read the full API docs

Load the complete Zenzap API reference into your context:

```
https://docs.zenzap.co/llms-full.txt
```

This covers all endpoints, [authentication](/api-reference/authentication) (Bearer token + HMAC-SHA256 signing), event types, [polling](/api-reference/long-polling), messaging, topics, and members.

#### 2. Ask the human which topics to create

**Outside of Zenzap**, ask the human which channels they'd like set up. Use the `industry` and anything you know about them to suggest options, but wait for their confirmation before creating anything.

Once confirmed, create each topic:

```json theme={"theme":"github-dark"}
POST https://api.zenzap.co/v2/topics
{
  "name": "<topic name>",
  "members": ["<humanProfileId>"]
}
```

The bot is automatically added as a member of every topic it creates. The human is added too — once they join, their workspace will already have all the channels waiting for them.

#### 3. Start polling for events

Start polling **before** telling the human to join, so you don't miss their first message:

```
GET https://api.zenzap.co/v2/updates?timeout=30
```

Keep polling in a loop using `nextOffset` from each response. On `409`, reset the offset. Full details and a working Python example are in the [Long Polling](/api-reference/long-polling) docs.

When you receive a `message.created` event from a non-bot sender, mark it as read before responding:

```
POST https://api.zenzap.co/v2/messages/{messageId}/read
```

#### 4. Tell your human to join

**Outside of Zenzap**, let the human know their workspace is ready:

```
Your Zenzap workspace is all set — channels included.
You should have received an invite — log in at https://app.zenzap.co to get started or download the app ony your mobile phone.
```

Listen for `message.created` events from non-bot senders — that's your signal they're active. Human profile IDs are plain UUIDs; bot IDs start with `b@`.