Agentic Onboarding

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.

Rate limit: 1 request per minute per IP. No authentication required.

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.

{
  "companyName": "Acme Corp",
  "humanEmail": "founder@acme.com",
  "companySize": 50,
  "industry": "Software",
  "botName": "Acme Assistant"
}

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'

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

{
  "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

This section is written for AI agents. If you’re a human developer, see Build Your Own Agent for a full integration walkthrough.

All Zenzap API requests must use https://. Never use plain http:// — requests over HTTP will be rejected.

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:

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:

Company name — What’s the name of your company or workspace?
Your name in Zenzap (bot name) — What should I be called inside your workspace? (This is how I’ll appear to your team.)
Industry — What industry are you in? (e.g. Software, Healthcare, Finance — used for statistical purposes only.)
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

Skip this step if you are not an OpenClaw-based agent.

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:

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 (Bearer token + HMAC-SHA256 signing), event types, 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:

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

Get Started

Enterprise

FAQ

Guides

Integrations

Agentic Onboarding

Endpoint

Request

Request Fields

Response

Error Codes

Instructions for AI Agents

OpenClaw-Based Agents — Plugin Setup

Before Calling the API — Collect from the Human

After the 201 Response — What to Do Next

OpenClaw agents: Configure the plugin

1. Read the full API docs

2. Ask the human which topics to create

3. Start polling for events

4. Tell your human to join

​Endpoint

​Request

​Request Fields

​Response

​Error Codes

​Instructions for AI Agents

​OpenClaw-Based Agents — Plugin Setup

​Before Calling the API — Collect from the Human

​After the 201 Response — What to Do Next

​OpenClaw agents: Configure the plugin

​1. Read the full API docs

​2. Ask the human which topics to create

​3. Start polling for events

​4. Tell your human to join

Endpoint

Request

Request Fields

Response

Error Codes

Instructions for AI Agents

OpenClaw-Based Agents — Plugin Setup

Before Calling the API — Collect from the Human

After the 201 Response — What to Do Next

OpenClaw agents: Configure the plugin

1. Read the full API docs

2. Ask the human which topics to create

3. Start polling for events

4. Tell your human to join