# Cancel your subscription Source: https://docs.bizzyco.ai/admin-guide/billing/cancel Cancel a paid plan in-app — what you keep until period end, and the optional exit survey New You can cancel a paid subscription **entirely inside Bizzy**. Cancellation takes effect at the **end of your current billing period**: you keep full access until then, and your account drops back to the Free plan afterward. ## Prerequisites * You must be an **Owner** or **Admin** to cancel the subscription * Your account must be on an active **paid** plan or a **paid trial** (Free accounts have nothing to cancel) ## Start a cancellation From **Settings > Account > Billing**, select **Cancel subscription**. The link appears only when your account has an active paid plan or a paid trial. This opens a two-step flow. ### Step 1 — Review what changes The first screen confirms what you're cancelling: * Your **current plan** and the date your access runs until (the end of the current billing period) * A **"What you'll lose"** summary — your current counts of team seats, businesses, agents, MCP servers, and automations, which become read-only once you drop back to Free From here you can choose **Keep my subscription** to back out with no change, or **Continue cancellation** to proceed. ### Step 2 — Tell us why (optional) The second screen asks why you're cancelling. This is **optional** — pick a reason and add any detail if you'd like to help us improve, or choose **Skip and cancel** to finish without answering. * **Skip and cancel** — cancels immediately, no reason recorded * **Submit and cancel** — cancels and records the reason you selected (plus any notes) Either button finishes the cancellation and returns you to the billing dashboard, where a confirmation banner shows the date your subscription will end. ## After you cancel * Your plan stays **active until the end of the current billing period** — you keep every paid feature until that date * The billing dashboard shows a persistent **"Subscription ending"** banner with the end date, so the scheduled cancellation is always visible (not just a one-time confirmation) * While a cancellation is scheduled, the **Cancel subscription** link is hidden and replaced by a **Resume subscription** button * At period end, the account returns to **Free**, and objects above the Free tier's limits become read-only (see [Limits](/admin-guide/billing/limits)) * You are **not** charged again for the cancelled plan * If you cancel during a **trial**, the trial simply won't convert — you keep access until it ends and are never charged ## Resume before the period ends Changed your mind? While your subscription is still active (before the end date), select **Resume subscription** from the "Subscription ending" banner — or the **Resume subscription** button in the billing header — on **Settings > Account > Billing**. Your plan continues uninterrupted at the same tier, you keep your current billing period, and the cancellation is cleared. Once the period has already ended and you've dropped to Free, resuming is no longer available — start a new subscription from the [upgrade page](/admin-guide/billing/upgrade) instead. ## Frequently asked questions No. Cancellation is scheduled for the end of your current billing period. You keep full access to your paid plan until that date, then the account drops to Free. No. The reason step is optional — **Skip and cancel** finishes without recording one. Cancelling stops the next renewal; the current period is not prorated or refunded. You keep access for the time you've already paid for. Yes, as long as the period hasn't ended yet. Select **Resume subscription** from the "Subscription ending" banner on the billing page. Your plan continues at the same tier with no interruption. Nothing is deleted. Objects above the Free tier's limits become read-only until you're back within Free limits or you resubscribe. See [Limits](/admin-guide/billing/limits). ## Next steps Resubscribe or switch tiers What becomes read-only on the Free plan # Credits Source: https://docs.bizzyco.ai/admin-guide/billing/credits Pre-pay for usage beyond your plan with one-time top-ups or auto top-up Credits are a USD balance on your account that Bizzy draws from when usage exceeds your monthly plan allowance. Every consumable — LLM tokens, storage, email sends, SMS, and voice minutes — bills against credits at the per-tier overage rate. API and MCP requests are rate limited rather than metered, so they never draw on credits. For the full per-tier overage table and how usage is tracked, see [Usage and metrics](/admin-guide/billing/usage). ## Prerequisites * You must be an **Owner** or **Admin** to view the credit balance, purchase credits, or change auto top-up settings * Credit purchases use the same payment method as your subscription ## View your credit balance 1. Navigate to **Settings > Account > Billing** 2. Find the **Credits** card The card shows: | Field | Meaning | | ----------------------- | -------------------------------------------------------------------------------------------------------------------- | | **Current balance** | Available credits in USD. A **Low Balance** badge appears when the balance is at or below your low-balance threshold | | **Lifetime added** | Total credits ever purchased or auto-topped-up | | **Lifetime spent** | Total credits ever consumed by overages | | **Recent Transactions** | 5 most recent credit movements (purchase, auto top-up, consumption, refund) with amount and running balance | If you have more than 5 transactions, a **History →** button expands the list to show all movements. ## One-time credit purchase To buy credits without enabling auto top-up: 1. On the **Credits** card, click **Purchase Credits** 2. In the **Purchase Credits** dialog, enter an amount in USD 3. Click **Purchase** 4. Complete payment in the embedded Stripe Checkout form. Apple Pay, Google Pay, and Link appear inside the same payment form when your browser supports them — no separate wallet button row The amount field is free-form: the default is **$10**, the minimum is **$5**, and the maximum is **\$1,000** per purchase. Credits land in your account immediately on successful payment. ### After you submit Once you click **Pay**, one of three outcomes appears on the billing page: | Outcome | What you see | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Immediate success** | The Credits card refreshes with the new balance. | | **Payment processing** | A notice reading "Your payment is processing. We'll email you when it completes." Credits are added to your account once the payment settles (typically minutes for most methods). | | **Payment error** | A notice reading "We couldn't confirm your payment. Please try again." No credits are added; re-open the purchase dialog to retry with a different card if needed. | The processing outcome applies to bank-debit methods (SEPA, BACS, and similar) that settle asynchronously. Card payments resolve immediately. Credits do not expire and roll over month to month. They are not refundable except where required by law. ## Auto top-up Auto top-up keeps your credit balance topped up automatically so usage never gets cut off mid-month. It's **off by default**. To configure auto top-up: 1. On the **Credits** card, in the **Auto Top-Up** section, click **Enable** (or **Manage** if already enabled) 2. In the **Auto Top Up** dialog, toggle **Enable auto top up** on 3. Confirm your default payment method, or add one if none is on file 4. Set **When credits are below** — the balance at which a top-up fires 5. Set **Purchase this amount** — how much to add per top-up 6. Click **Save** | Setting | Range | | ---------------------------------- | ----------------------------- | | When credits are below (threshold) | \$0 up to the purchase amount | | Purchase this amount | $5 – $100,000 | When your balance drops below the threshold, Bizzy charges your saved payment method for the purchase amount and credits your balance. You receive a `credit_auto_recharge_triggered` notification on each successful top-up and a `credit_purchase_failed` notification if the charge fails. A failed auto top-up does not retry automatically. Update your default card on the [Payment methods](/admin-guide/billing/payment-methods) page and trigger a one-time purchase to restore service. ## What happens when credits run out When your monthly allowance is exhausted **and** your credit balance is depleted, behavior depends on the consumable: * **LLM tokens (agent chat).** Agent conversations are blocked. The chat shows an **Out of Credits** card with a button to purchase more * **Other consumables (email, SMS, voice, storage).** New requests fail until you top up credits, your billing cycle resets, or you upgrade * **API and MCP requests.** Unaffected — they are governed by per-minute rate limits, not credits * **Free tier.** Same behavior — Free accounts can purchase credits to keep working past the included allowance You also receive notifications as you approach exhaustion: | Notification | When | | ------------------------- | --------------------------------------------------------------------------------------------- | | `credit_balance_low` | Balance falls below your auto top-up threshold (or a default threshold if auto top-up is off) | | `credit_balance_depleted` | Balance reaches zero | ## Next steps See current usage and per-tier overage rates View and pay invoices for credit purchases # Billing Source: https://docs.bizzyco.ai/admin-guide/billing/index Manage billing, subscriptions, and usage in Bizzy Bizzy uses an account-based subscription model with tiered pricing. As an administrator, you manage billing at the account level, which covers all organizations and team members under your account. ## Billing Concepts ### Account-Based Billing Billing in Bizzy is managed at the **account** level, not the organization level. A single account can contain multiple organizations, and all usage across organizations counts toward your account's limits. ``` Account (Billing Entity) ├── Subscription (Tier & Limits) ├── Organizations (Workspaces) │ └── Members (Users) └── Account Members (Billing Admins) ``` ### Subscriptions Your subscription determines: * **Resource limits** - How many organizations, seats, agents, MCP servers, and automations you can create * **Consumable allowances** - Monthly limits for LLM tokens, storage, email sends, SMS, and voice minutes * **Request rate limits** - How many API and MCP requests you can make per minute * **Overage rates** - The per-unit price once an included allowance is used up All tiers include the full platform and every AI model — tiers differ in capacity, included usage, and overage rates, not in what the agent can do. ### Seats Seats represent unique users across all organizations in your account. A user who belongs to multiple organizations only counts as one seat. Each tier includes a certain number of seats, and you can purchase additional seats on paid tiers. ## Quick Reference | Tier | Price | Seats | Businesses | Agents | LLM Tokens/mo | | ---------------- | -------- | --------- | ---------- | --------- | ------------- | | **Free** | \$0 | 1 | 1 | 3 | 100K | | **Starter** | \$25/mo | 3 | 3 | 10 | 1M | | **Professional** | \$100/mo | 10 | 10 | 50 | 10M | | **Enterprise** | Custom | Unlimited | Unlimited | Unlimited | Unlimited | See [Usage and metrics](/admin-guide/billing/usage) for the full object-and-consumable table including MCP servers, automations, storage, email sends, SMS, and voice minutes. ## Billing Topics Compare features, resource limits, and AI model access across all tiers Subscription pricing, seat add-ons, trial periods, and billing cycles Current usage, account object limits, and per-tier overage rates Balance, one-time purchases, and auto-recharge Compare tiers and switch your subscription View, download, and pay invoices in-app Add, remove, and set the default card on file Edit your billing contact, address, and tax details Cancel in-app — keep full access until the end of the billing period Warning thresholds and downgrade behavior ## Managing your subscription From **Settings > Account > Billing** you can: * View current usage and remaining allowances ([Usage and metrics](/admin-guide/billing/usage)) * Upgrade or downgrade your subscription ([Upgrade](/admin-guide/billing/upgrade)) * Purchase credits or enable auto-recharge ([Credits](/admin-guide/billing/credits)) * View, download, and pay invoices ([Invoices](/admin-guide/billing/invoices)) * Manage saved cards ([Payment methods](/admin-guide/billing/payment-methods)) * Edit your billing contact, address, and tax details ([Billing profile](/admin-guide/billing/profile)) * Cancel your subscription ([Cancel](/admin-guide/billing/cancel)) Only account members with **Owner** or **Admin** roles can access billing settings and make changes to the subscription. # Invoices Source: https://docs.bizzyco.ai/admin-guide/billing/invoices View, download, and pay the invoices on your Bizzy account New See every invoice Bizzy has issued to your account — directly inside the app, with links out to Stripe-hosted copies and downloadable PDFs. ## Prerequisites * You must be an **Owner** or **Admin** to view invoices * An active Stripe customer record (created automatically the first time you save a card or upgrade a plan) ## Open the page 1. Navigate to **Settings > Account > Billing** 2. Click **View invoices** in the page header You'll land on the Invoices table. ## What you'll see Each row shows: | Column | What it means | | --------------- | ---------------------------------------------------------- | | **Date** | When the invoice was issued | | **Description** | The line description, or the billing period if none | | **Amount** | Total due in the invoice currency | | **Status** | Current state — see [statuses](#statuses) below | | **Actions** | View hosted invoice, Download PDF, and (when open) Pay now | The list shows the most recent 20 invoices first. Click **Load more** to append the next page. ## Actions | Action | What happens | | ----------- | ------------------------------------------------------------------------------------------------------------------- | | **View** | Opens the Stripe-hosted invoice page in a new tab — usable for self-service payment and download | | **PDF** | Downloads the invoice PDF directly from Stripe | | **Pay now** | Available on **Open** and **Past due** invoices. Charges your default card on file in-app — see [Pay now](#pay-now) | ### Pay now Click **Pay now** on any open invoice to charge your default card without leaving the app. A confirmation dialog shows the card that will be used and the exact amount. * If you have more than one card on file, click **Use a different card** in the dialog to pick another one before confirming. * If the charge is declined, the decline reason appears inline in the dialog so you can switch cards and retry — your session stays put. * If you don't have a card on file yet, the dialog links to **Payment methods** so you can add one and try again. On a successful charge, the row's status flips to **Paid** automatically and your account state catches up (for example, a past-due account returns to active). ## Statuses | Status | Meaning | | ----------------- | ------------------------------------------------------------------------------- | | **Paid** | Charge succeeded; nothing more is owed | | **Open** | Finalized and awaiting payment, not yet overdue | | **Past due** | Open invoice whose due date has passed — pay soon to avoid service interruption | | **Draft** | Not finalized yet; usually a transient state during billing cycles | | **Uncollectible** | Stripe marked the invoice unrecoverable (rare; contact support if you see this) | | **Void** | The invoice was canceled and isn't owed | ## Empty state If you haven't been charged yet — or your account doesn't have a Stripe customer record yet — the page shows **"No invoices yet — they'll appear here after your first charge."** This is expected for trial-only accounts and brand-new sign-ups; no action is needed. ## Related Manage the cards used to settle invoices How credit purchases appear as invoices # Understanding Limits Source: https://docs.bizzyco.ai/admin-guide/billing/limits Learn how Bizzy enforces usage limits and what happens when you exceed them Bizzy enforces three types of limits: resource limits (for creating objects), consumable limits (for metered usage), and rate limits (for API and MCP requests). This page explains how each type of limit works and what to expect as you approach or exceed them. ## Types of Limits ### Resource Limits Resource limits control how many of each resource type you can create: * Businesses * Seats (team members) * Agents * MCP Servers * Automations **Resource limits are hard limits.** When you reach the limit, you cannot create additional resources until you upgrade your tier or delete existing resources. ### Consumable Limits Consumable limits control your monthly usage of: * LLM Tokens * Email Sends * SMS * Voice Minutes * Storage **Consumable limits have flexible enforcement** with warning thresholds and a grace period for paid tiers. Free tier has a hard cutoff at 100%. ### Rate Limits Rate limits control how many API and MCP requests you can make **per minute**. They are not monthly allowances: nothing accrues, nothing runs out, and requests are never billed per call. See [API and MCP Rate Limits](#api-and-mcp-rate-limits) below. ## Warning Thresholds Bizzy monitors your consumable usage and sends notifications at key thresholds: | Threshold | Level | What Happens | | --------- | -------- | ----------------------------------------------------------- | | **90%** | Warning | Email and in-app banner alerting you to high usage | | **100%** | Critical | Email and in-app modal; overage billing begins (paid tiers) | | **110%** | Cutoff | Service paused until next billing cycle or upgrade | Each threshold for a resource is evaluated as usage for that resource is reported, so a warning arrives with the activity that crosses the threshold. Each threshold notifies you once per billing period. ### Free Tier Warnings When you approach your limits on the Free tier: * **At 90%:** "You've used 90% of your monthly allowance. Upgrade to continue." * **At 100%:** "You've reached your limit. Upgrade to Starter for more capacity." The Free tier has a **hard cutoff at 100%**. There is no grace period or overage billing. Service is paused until your next billing cycle or you upgrade. ### Paid Tier Warnings When you approach your limits on paid tiers (Starter, Professional, Enterprise): * **At 90%:** "You've used 90% of your monthly allowance. Overage billing will apply beyond 100%." * **At 100%:** "You've exceeded your allowance. Overage charges: \$X.XX. Consider upgrading." * **At 110%:** "You've reached the maximum overage limit. Service paused until next billing cycle or upgrade." Paid tiers have a **soft limit with a 10% overage allowance**. You can continue using the service up to 110% of your monthly allowance, with overage charges applying for usage between 100% and 110%. At 110%, service is paused until you purchase more credits or your billing cycle resets. ## Viewing Your Usage You can monitor your usage at any time from the usage dashboard in your account settings. The dashboard shows: * Current usage for all consumables * API and MCP request counts for the period, alongside your rate limits * Remaining allowance for the billing period * Progress bars indicating usage percentage * Days until your allowances reset * Historical usage trends To access your usage dashboard: 1. Go to your account settings 2. Select **Usage** from the sidebar 3. View your current period usage and resource capacity ## What Happens When Limits Are Exceeded ### Resource Limits When you reach a resource limit: * You cannot create new resources of that type * Existing resources continue to work normally * You see an error message explaining the limit * You're prompted to upgrade or delete existing resources ### Consumable Limits (Free Tier) When you reach 100% on the Free tier: * The affected service is paused immediately * Existing data is preserved * You can still access your account and view data * AI features (agents, automations) that consume tokens are disabled * API and MCP requests keep working — they are rate limited, not metered ### Consumable Limits (Paid Tiers) When you exceed your allowance on paid tiers: 1. **100% - 110%:** Overage billing applies, service continues 2. **At 110%:** Service is paused 3. You receive email notifications at each threshold 4. Service resumes when: * You purchase additional credits * Your billing cycle resets * You upgrade to a higher tier ## Managing High Usage Check your usage dashboard regularly, especially during high-activity periods. Set up internal alerts when you approach 80% of your limits. If you anticipate high usage, purchase credits in advance. Credits can be used immediately and carry over between billing cycles. Review your agents and automations for opportunities to reduce token consumption. Shorter prompts and more efficient workflows can significantly reduce usage. If you consistently exceed your limits, upgrading to a higher tier is often more cost-effective than paying overage charges. Compare the cost of overages against the higher tier pricing. ## Limit Reset * **Monthly allowances** reset on your billing cycle anniversary date * **Resource limits** do not reset; they are permanent caps * **Credit balances** do not expire and carry over between periods Your billing cycle anniversary is the day you started your subscription. For example, if you subscribed on the 15th, your allowances reset on the 15th of each month. ## Upgrading to Increase Limits When you upgrade your subscription: * New resource limits take effect immediately * New consumable allowances are prorated for the current period * You're charged a prorated amount for the upgrade * Any existing overage usage is resolved with the new higher limits ## API and MCP Rate Limits Rate limits work differently from consumable limits. Consumable limits track your total monthly usage; rate limits control how many requests you can make per minute. API and MCP access is included on every tier, including Free, and what scales with your tier is the request rate. | Service | Free | Starter | Professional | Enterprise | | ---------------- | ---- | ------- | ------------ | ---------- | | **API requests** | 10 | 60 | 300 | 1,000 | | **MCP requests** | 10 | 30 | 100 | 300 | Rates are per minute. API and MCP have independent allowances, so heavy API traffic never consumes your MCP capacity. ### How Rate Limits Work * **Continuous refill:** Your allowance refills steadily rather than resetting on a fixed minute boundary. A Free-tier account regains roughly one request every six seconds; a Professional one regains five per second * **429 responses:** When you exceed your API rate limit, requests return a `429 Too Many Requests` error; MCP tool calls return a JSON-RPC rate-limit error * **No metering, no overage billing:** Requests are not counted against a monthly allowance, and exceeding a rate limit never incurs a charge or draws on credits. Your request rate is set by your tier — there is no top-up that raises it, so upgrade the tier instead * **Automatic recovery:** Wait for the allowance to refill and your requests succeed again — there is nothing to purchase or reset Your current rate limits are shown on the billing page under **Request Rate Limits**. If your integration needs a higher request rate, upgrade your tier or contact support to discuss your use case. ## Downgrade Behavior When you downgrade to a tier with lower limits, your existing resources are preserved but anything over the new caps is **soft-disabled** — paused, not deleted. ### What Happens to Excess Resources * **Nothing is deleted:** Your existing agents, automations, and other resources remain intact with all their configuration * **Newest first:** The most recently created items are disabled first; the organization owner is never disabled * **Creation blocked:** You cannot create new resources of that type until you're under the limit * **One-click re-activation:** Upgrade again (or remove other items to get under the cap) and you can re-activate a disabled item from its page — Bizzy verifies you're within the limit before re-enabling it ### Examples | Scenario | Result | | ----------------------------------------------------------------- | --------------------------------------------------------------------------- | | Professional (50 agents) → Starter (10 agents) with 25 agents | The 15 newest agents are paused until re-activated | | Professional (100 automations) → Starter (25) with 40 automations | The 15 newest automations are paused | | Starter (3 seats) → Free (1 seat) with 3 members | The 2 newest non-owner members are disabled until you're back under the cap | ### Consumable Allowances on Downgrade * New consumable limits take effect at the start of your next billing cycle * Current period usage is not affected * If you've already exceeded the new tier's limit, overage billing continues until cycle reset Plan your downgrade carefully. Decide in advance which agents and automations matter most — the newest ones are paused first. Compare tier features and limits View pricing and consumable allowances # Payment methods Source: https://docs.bizzyco.ai/admin-guide/billing/payment-methods View, add, set as default, and remove the payment methods saved on your Bizzy account New Manage the payment methods saved on your account directly inside Bizzy — no need to leave Bizzy for routine changes. ## Prerequisites * You must be an **Owner** or **Admin** to view or change payment methods * An active billing customer record (created automatically the first time you save a payment method or upgrade a plan) ## Open the page 1. Navigate to **Settings > Account > Billing** 2. Click **Manage payment methods** in the page header You land at `/settings/account/billing/payment-methods`. ## What you can do | Action | What happens | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Add payment method** | Opens an in-app dialog with a secure form powered by Stripe Checkout. Save a card or US bank account (ACH); Apple Pay, Google Pay, and Link also appear automatically when supported by your browser or device. After your bank approves it (including any 3-D Secure step), it appears in the list. | | **Set as default** | Marks the payment method as the one used for subscription renewal, credit top-ups, and consumable overage charges. The current default's row shows a **Default** badge. | | **Remove** | Detaches the payment method from your account immediately. Confirm in the prompt before it's removed. You can't remove your last payment method — add a new one first if you want to swap. | The first payment method you add is automatically promoted to default. ### After you add a payment method Once you complete the form and click **Save payment method**, one of three outcomes appears at the top of the page: | Outcome | What you see | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Immediate success** | The payment method appears in your list and is set as default if it's your first one. | | **Save processing** | A notice reading "Your payment is processing. We'll email you when it completes." This can occur for bank-debit methods that settle asynchronously. | | **Error** | A notice reading "We couldn't save your payment method. Please try again." Nothing was saved; try again or use a different payment method. | ## Empty state When no payment methods are saved yet, the page shows an empty state with a prominent **Add payment method** call-to-action. The same dialog opens whether you click the empty-state button or the **Add payment method** button in the page header. ## Default payment method behavior * Exactly one payment method is the default at any time. Setting a non-default one as default replaces the previous one. * If you remove the default and others remain, Bizzy automatically promotes the most-recently-added remaining payment method on the next page load. To pick a different default, use **Set as default** on the one you prefer. * Subscription invoices, credit top-ups, and overage charges all bill the default payment method. * At least one payment method must always be on file. Removing your only one is blocked; add a replacement first. ## If a payment fails When we can't charge your default payment method for a subscription renewal, your account is marked **past due** and we automatically retry your card several times over the following weeks. Your services keep working while we retry, so there's no fixed deadline. Updating your payment method points the next retry at the new card — the past-due state clears once that retry succeeds, not the moment you save the card. To restore your account right away, use **Pay now** on the open invoice (see [Invoices](/admin-guide/billing/invoices#pay-now)) to charge the card immediately. You'll receive reminder emails while your payment is past due: | When | Notification | What it tells you | | -------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ | | Right away | Payment failed | The first attempt didn't go through; update your payment method to keep your subscription. | | \~3 days later | Payment still failing | We still couldn't collect payment; please update your card. | | \~7 days later | Payment still failing — last reminder | A final reminder while retries continue. | If the retries are eventually exhausted, the subscription is canceled and Bizzy automatically: * Moves the account to the **Free** plan * Disables (but does not delete) resources beyond Free-tier limits — agents, automations, MCP servers, and extra members * Sends a final "subscription canceled" email summarizing what happened Your data is preserved throughout — nothing is deleted. To restore your subscription, [add or set a default payment method](#open-the-page) in-app, then pick a plan on the [Upgrade page](/admin-guide/billing/upgrade). Disabled resources can be re-activated once you're back within that tier's limits. ## Related View, download, and pay invoices in-app Update your billing contact, address, and tax ID How credits and auto-recharge use your default payment method # Pricing & Consumables Source: https://docs.bizzyco.ai/admin-guide/billing/pricing Understand Bizzy pricing, monthly allowances, and overage billing Bizzy uses a subscription-based pricing model with monthly consumable allowances. This page explains how pricing works, what's included in each tier, and how overage billing applies. ## Subscription Pricing | Tier | Monthly | Annual | Savings | | ---------------- | ------- | ------- | ------------- | | **Free** | \$0 | - | - | | **Starter** | \$25 | \$250 | 2 months free | | **Professional** | \$100 | \$1,000 | 2 months free | | **Enterprise** | Custom | Custom | Contact sales | Annual billing saves you 2 months free. The Starter tier includes a 30-day free trial with no payment method required until the trial ends. ## Monthly Consumable Allowances Each tier includes monthly allowances for consumable resources. These reset on your billing cycle anniversary date. | Consumable | Free | Starter | Professional | Enterprise | | -------------- | ------- | --------- | ------------ | ---------- | | **LLM Tokens** | 100,000 | 1,000,000 | 10,000,000 | Custom | ### Understanding Consumables * **LLM Tokens** - Tokens used when AI agents process messages, generate responses, or run automations. Both input and output tokens count toward your limit. ## API & MCP Request Rates API and MCP access is included on every tier and is entitled by **request rate**, not a monthly call allowance. Requests are never billed per call, and there is nothing to run out of — the limit is how many requests you may make in a given minute. | Service | Free | Starter | Professional | Enterprise | | ---------------- | ---- | ------- | ------------ | ---------- | | **API requests** | 10 | 60 | 300 | 1,000 | | **MCP requests** | 10 | 30 | 100 | 300 | Rates are per minute. API and MCP have independent allowances, so heavy API traffic never eats into your MCP capacity. Exceeding a rate limit does not incur charges and does not pause your account. Your allowance refills continuously rather than resetting on a fixed minute boundary, so capacity returns a little at a time after a burst. See [Rate Limits](/api-reference/rate-limits) for handling guidance. ## Credit System Paid tiers (Starter, Professional, Enterprise) use a credit system for usage beyond your monthly allowance. ### How Credits Work 1. Each month, you receive your tier's consumable allowances 2. Usage is first deducted from your monthly allowance 3. When you exceed your allowance, usage is automatically deducted from your credit balance in real-time 4. You can purchase credits at any time from the billing dashboard ### Overage Rates When you exceed your monthly allowance, the following rates apply: | Consumable | Rate | Unit | | -------------- | ------ | ----------------- | | **LLM Tokens** | \$0.10 | per 10,000 tokens | **Free tier has no overage billing.** When you reach 100% of your limit on the Free tier, service is paused until the next billing cycle or you upgrade. Paid tiers allow usage up to 110% of the limit before pausing. ### Credit Purchase Options You can purchase credits from the **Billing** section in your account dashboard. Credits are available in the following amounts: | Amount | Credits | | ------ | -------------- | | \$10 | 1,000 credits | | \$20 | 2,000 credits | | \$50 | 5,000 credits | | \$100 | 10,000 credits | **Credit conversion rate:** 1 credit = \$0.01. Credits never expire and carry over between billing cycles. ### Example: Overage Calculation A Professional tier account with a 10M token allowance and \$50 credit balance: | Usage Range | Cost | | ----------------- | -------------------------------------------- | | 0 - 10M tokens | Included in subscription | | 10M - 15M tokens | $50 from credit balance ($0.10 per 10K) | | Beyond 15M tokens | Paused until credits purchased or next cycle | ## Additional Seats If you need more seats than included in your tier, you can purchase additional seats. | Tier | Included Seats | Additional Seat Cost | | ---------------- | -------------- | -------------------- | | **Free** | 1 | Not available | | **Starter** | 3 | \$5/seat/month | | **Professional** | 10 | \$8/seat/month | | **Enterprise** | Custom | Custom | Additional seats are billed monthly and prorated when added mid-cycle. ## Trial Period The Starter tier includes a **30-day free trial**: * Full access to all Starter tier features and limits * No payment method required to start * Automatic downgrade to Free tier if not converted * Convert to paid at any time during the trial Stripe manages the trial period. You'll receive email reminders before your trial ends to add a payment method and continue your subscription. The Professional tier does not include a trial period. You can start with the Starter tier trial and upgrade to Professional at any time. ## Billing Cycle * **Monthly subscriptions** are billed on the same day each month * **Annual subscriptions** are billed once per year on your subscription anniversary * **Consumable allowances** reset on your billing cycle anniversary date * **Upgrades** take effect immediately with prorated charges * **Downgrades** take effect at the end of your current billing period ## Managing Your Billing You can manage all billing settings from your account dashboard: * View current usage and remaining allowances * Purchase credits * Add or remove seats * Upgrade or downgrade your subscription * Update payment methods * Download invoices Compare tier features and limits Learn how limits are enforced # Billing profile Source: https://docs.bizzyco.ai/admin-guide/billing/profile Edit the billing contact, billing address, and tax ID stored on your Bizzy account New Keep the contact, address, and tax details that appear on your invoices and receipts up to date — all in one place inside Bizzy. ## Prerequisites * You must be an **Owner** or **Admin** to view or change the billing profile ## Open the page 1. Navigate to **Settings > Account > Billing** 2. Click **Billing profile** in the page header You land at `/settings/account/billing/profile`. The form is pre-populated with your account's current values. ## What you can edit | Section | Fields | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Billing contact** | **Billing email** (required) — where billing notifications and receipts are sent — and an optional **Company name**. | | **Billing address** | Address line 1, address line 2, city, state/province, postal code, and country. **Country** is chosen from a list of ISO 3166-1 alpha-2 countries. | | **Tax** | A **Tax ID type** chosen from a list (for example United States — EIN, European Union — VAT, United Kingdom — VAT) and the **Tax ID** value itself. When you enter a Tax ID value, you must also select its type so it can be applied to your invoices. | ## Save your changes Click **Save changes**. Bizzy validates the form and: * Surfaces inline errors beneath any field that needs attention: * The billing email is required and must be a valid email address. * A country is required once you start filling in the billing address, and is chosen from the ISO 3166-1 alpha-2 list. The postal code is checked against the selected country's format for the United States, Canada, and the United Kingdom (other countries are accepted as-is). * A Tax ID requires a type, and must be 50 characters or fewer with no leading or trailing spaces. * On success, saves your details and shows a confirmation toast. The form reflects the saved values. Your billing details are also written through to your payment provider so the email, name, address, and tax ID on your invoices and receipts stay in sync. If that sync can't be completed, the save is rolled back and an inline error asks you to try again — so your Bizzy account and your invoices never drift out of step. ## Related Manage the cards and bank accounts on file View, download, and pay invoices in-app # Subscription Tiers Source: https://docs.bizzyco.ai/admin-guide/billing/tiers Compare Bizzy subscription tiers and choose the right tier for your organization Bizzy offers four subscription tiers designed to scale with your business needs. Each tier provides different resource limits, consumable allowances, and overage rates. ## Tier Overview | Tier | Price | Billing Options | Trial | | ---------------- | ----------- | ----------------- | ---------- | | **Free** | \$0/month | Monthly only | None | | **Starter** | \$25/month | Monthly or Annual | 30 days | | **Professional** | \$100/month | Monthly or Annual | None | | **Enterprise** | Custom | Custom | Negotiated | **Annual billing discount:** Save 2 months free when you choose annual billing. Starter annual is $250/year and Professional annual is $1,000/year. ## Resource Limits Resource limits determine how many of each resource type you can create within your account. | Resource | Free | Starter | Professional | Enterprise | | -------------------- | ------------- | -------------- | -------------- | ---------- | | **Businesses** | 1 | 3 | 10 | Unlimited | | **Seats (included)** | 1 | 3 | 10 | Custom | | **Additional Seats** | Not available | \$5/seat/month | \$8/seat/month | Custom | | **MCP Servers** | 2 | 5 | 20 | Unlimited | | **Agents** | 3 | 10 | 50 | Unlimited | | **Automations** | 5 | 25 | 100 | Unlimited | Resource limits are **hard limits**. You cannot create resources beyond your tier limit. To add more resources, upgrade to a higher tier. ## AI Model Access Every tier can use every available agent model — there is no model gating. Model usage is billed by the token through the **LLM Tokens** consumable, so the cost difference between models shows up in your usage, not your tier. See [Agent Models](/user-guide/agents/models) for the model list and guidance on choosing one. ## What Every Tier Includes All tiers include the full platform: unified inbox, contacts and customers, agents, automations, files, domains, the REST API, and the MCP server. Tiers differ in capacity (the resource limits above), included usage (see [Pricing](/admin-guide/billing/pricing)), and overage rates. **Enterprise** additionally offers custom limits, negotiated pricing, and a support SLA. ## API & MCP Rate Limits API and MCP access is included on every tier, including Free. What scales with your tier is the **request rate** — how many requests per minute you may make. There is no monthly call allowance and no per-call billing. | Service | Free | Starter | Professional | Enterprise | | ---------------- | ---- | ------- | ------------ | ---------- | | **API requests** | 10 | 60 | 300 | 1,000 | | **MCP requests** | 10 | 30 | 100 | 300 | Rates are per minute, and API and MCP are limited independently. See [Rate Limits](/api-reference/rate-limits) for handling guidance. ## Choosing the Right Tier The Free tier is perfect for individuals who want to explore Bizzy's capabilities. You can create a limited number of agents and automations and try every part of the platform. **Best for:** Personal use, evaluation, small side projects The Starter tier is designed for small businesses or teams who need more capacity and included usage. The 30-day trial lets you experience the full tier before committing. **Best for:** Small businesses, startups, growing teams The Professional tier provides significantly higher limits, ten times the included usage of Starter, and the cheapest overage rates. It's ideal for businesses running many agents and automations day to day. **Best for:** Established businesses, agencies, teams with heavy usage The Enterprise tier offers unlimited resources, custom pricing, a support SLA, and negotiated terms for large organizations. **Best for:** Large organizations, enterprises with custom requirements ## Upgrading Your Tier You can upgrade your subscription at any time from the billing settings in your dashboard. When you upgrade: * New limits take effect immediately * You're charged a prorated amount for the remainder of the billing period * All your existing data and configurations are preserved View detailed pricing and consumable limits Learn how limits are enforced # Upgrade your plan Source: https://docs.bizzyco.ai/admin-guide/billing/upgrade Compare tiers and switch your subscription from the upgrade page New The upgrade page at **`/billing/upgrade`** is the conversion entry point for changing plans. Every paid plan transition — Free → Starter, Starter → Professional, switching billing intervals — starts here. If your account already has a subscription, switching plans now happens **entirely inside Bizzy**: you review the prorated charge on a confirmation screen and confirm. Only your **first** purchase (from the Free plan) still goes through Stripe Checkout to collect payment details. ## Prerequisites * You must be an **Owner** or **Admin** to change the subscription * Open the page from anywhere in the app at `/billing/upgrade`, or from **Settings > Account > Billing > Upgrade plan** ## What the page shows The upgrade page is a full-screen, no-sidebar layout designed to make the choice clear: * **Trial banner** at the top if your account is currently trialing — shows trial end date and a reminder to add a payment method before it ends * **Tier cards** for Free, Starter, Professional, and Enterprise with prices, included resource limits, and key features * **Billing-interval toggle** for Monthly vs. Annual (annual saves about 17%, equivalent to two months free) * **Plan comparison** table for a side-by-side view of features and limits * **FAQ** covering proration, cancellation, and downgrade behavior The **Professional** card is highlighted as the recommended plan. If you're on Enterprise, contact sales for any changes. ## Choose a plan Click the **Upgrade** (or **Switch to**) button on a tier card. Where you go next depends on your current state: | Current state | Where the button takes you | | --------------------------- | ----------------------------------------------------------------------------------------------------- | | Free | Stripe Checkout — enter payment details and confirm | | Trialing | In-app plan change — review proration and confirm without leaving Bizzy | | Paid (downgrade or upgrade) | In-app plan change — review proration and confirm without leaving Bizzy | | Enterprise | Redirected back to **Settings > Account > Billing** — Enterprise plans require sales-assisted changes | After payment or confirmation, the new tier takes effect immediately. ## Review and confirm For accounts that already have a subscription, the button opens the in-app plan-change screen at **`/settings/account/billing/subscription/change`**. It shows everything you need to decide before committing: * A **summary** of the switch — "Switching from *current plan* to *new plan*" * **Charged today (prorated)** — the amount due now for the remaining time in the current billing period at the new plan's rate * A **credit** line when the change leaves a balance in your favor (common on downgrades and interval switches) — applied to future invoices * **Next bill** — the recurring amount and the date it lands Click **Confirm change** to apply it. Bizzy updates the subscription in Stripe and returns you to the billing dashboard with a confirmation. Click **Cancel** to go back without changing anything. ### When a downgrade is blocked If the plan you're switching to has lower limits than your current usage, the confirmation screen replaces the proration card with a breakdown of exactly what's over the limit (for example, "Agents: 20 in use, 10 allowed"), and the **Confirm change** button is disabled. Reduce the listed resources, then return to the screen — the check re-runs automatically. Pre-validation only catches account objects (seats, businesses, agents, MCP servers, automations). Consumable usage above the new tier's allowance will simply bill as overages on the next cycle — see [Limits](/admin-guide/billing/limits) for details. ### Trials The Starter plan includes a **30-day free trial** — no payment method required up front. Professional and Enterprise plans do not include trials; you can start with the Starter trial and upgrade to Professional at any point during or after it. When your Starter trial ends: * If you've added a payment method, billing begins automatically * If you haven't, the account drops back to Free and any over-Free-tier objects become read-only (see [Limits](/admin-guide/billing/limits)) ## Frequently asked questions Yes. Stripe credits the unused portion of your current period and charges the prorated amount for the new tier on the same invoice. You see the charged-today, credit, and next-bill amounts on the in-app confirmation screen before confirming. Yes — pick a lower tier on the upgrade page. Bizzy runs a [pre-validation check](#when-a-downgrade-is-blocked) first; if your current usage exceeds the target tier's limits, the confirmation screen lists what to reduce and disables **Confirm change** until you're within the new plan's limits. Yes — cancel in-app from **Settings > Account > Billing > Cancel subscription**. Your plan stays active until the end of the current billing period, then drops back to Free. See [Cancel your subscription](/admin-guide/billing/cancel). Credits roll over and don't expire. Current-period overage usage continues to bill at your prior tier's overage rate; the new tier's rate applies starting next cycle. ## Next steps Compare tier features in detail Cancel in-app, effective at the end of the billing period # Usage and metrics Source: https://docs.bizzyco.ai/admin-guide/billing/usage Track resource counts, monthly consumable usage, and overage costs from the billing dashboard The usage dashboard shows your account's consumption against its plan in real time. Bizzy tracks two kinds of usage: **account objects** (countable things you create and delete) and **consumables** (monthly allowances that reset on your billing anniversary). To open the dashboard: 1. Navigate to **Settings > Account > Billing** 2. Scroll to the **Usage** section ## Account objects Account objects have hard limits per tier. When you reach a limit you can't create more of that object until you delete one or upgrade your plan. | Object | Free | Starter | Professional | Enterprise | | ------------------------ | ---: | ------: | -----------: | ---------: | | **Seats** (team members) | 1 | 3 | 10 | Unlimited | | **Businesses** | 1 | 3 | 10 | Unlimited | | **Agents** | 3 | 10 | 50 | Unlimited | | **MCP Servers** | 2 | 5 | 20 | Unlimited | | **Automations** | 5 | 25 | 100 | Unlimited | Each object's card on the dashboard shows your current count, the included plan limit, and a progress bar. Additional seats can be purchased on Starter, Professional, and Enterprise plans without changing tier. See [Pricing](/admin-guide/billing/pricing) for per-seat pricing. ## Consumables Consumables are metered usage that accrues during the billing period and resets on your billing-cycle anniversary date. | Consumable | Free | Starter | Professional | Enterprise | | ----------------- | ------: | --------: | -----------: | ---------: | | **LLM tokens** | 100,000 | 1,000,000 | 10,000,000 | Unlimited | | **Storage** | 100 MB | 1 GB | 10 GB | Unlimited | | **Email sends** | 100 | 1,000 | 10,000 | Unlimited | | **SMS** | 50 | 500 | 5,000 | Unlimited | | **Voice minutes** | 30 | 300 | 3,000 | Unlimited | Each consumable card shows: * The included allocation * Current period usage and a progress bar * The per-tier overage rate * Live overage cost so far this period (if any) ### Allocation header colors The progress bar color tracks your usage percentage: | Usage | Color | What it means | | ------------- | ------ | ------------------------------------------ | | Below 80% | Green | Healthy — well within plan | | 80% – 99% | Yellow | Approaching the included allocation | | 100% or above | Red | Allocation exhausted — overage rates apply | You also receive `usage_warning` notifications at 90% and `usage_limit_reached` at 100%. See [Notifications](/admin-guide/notifications) to configure delivery channels. ## API & MCP requests API and MCP requests are **not** consumables. They are entitled by request rate rather than a monthly allocation, so they are never metered against an allowance, never billed per call, and never trigger usage warnings. | Service | Free | Starter | Professional | Enterprise | | ---------------- | ---: | ------: | -----------: | ---------: | | **API requests** | 10 | 60 | 300 | 1,000 | | **MCP requests** | 10 | 30 | 100 | 300 | Rates are per minute, and the two services are limited independently. The usage dashboard still shows your API and MCP request **counts** for the period so you can see your traffic — there is no progress bar, because there is no allocation to fill. Your current rate limits are shown on the billing page under **Request Rate Limits**. ## Overage rates Once a consumable passes 100% of its allocation, additional usage bills against your [credit balance](/admin-guide/billing/credits) at the per-tier rate below. | Consumable | Unit | Free | Starter | Professional | Enterprise | | ----------------- | ---------- | -----: | ------: | -----------: | ---------: | | **LLM tokens** | per 10,000 | \$0.50 | \$0.40 | \$0.30 | Custom | | **Storage** | per 1 GB | \$0.25 | \$0.15 | \$0.10 | Custom | | **Email sends** | per 100 | \$0.15 | \$0.10 | \$0.05 | Custom | | **SMS** | per 10 | \$0.15 | \$0.10 | \$0.075 | Custom | | **Voice minutes** | per 10 | \$0.30 | \$0.20 | \$0.15 | Custom | All tiers — including Free — can purchase credits and pay overages. Enterprise overage pricing is set in your contract. Overage cost is rounded up by unit. For example, sending 110 emails when 100 are included on the Starter plan ($0.10 per 100) bills as one full overage unit = $0.10, not \$0.01. ## How usage is counted | Object or consumable | Counted at | | ------------------------------------------------ | --------------------------------------------------------------------------------- | | **Seats** | Every accepted invitation; revoked when a member is removed | | **Businesses, Agents, MCP Servers, Automations** | When the object is created (counter restored on delete) | | **LLM tokens** | Every token billed by the upstream model — input plus output | | **API requests** | Every authenticated request to the public REST API (recorded, not billed) | | **MCP requests** | Every authenticated tool invocation against the MCP server (recorded, not billed) | | **Storage** | Sum of bytes across all uploaded files (recomputed on upload and delete) | | **Email sends** | Every outbound email; received emails are not counted | | **SMS** | Every outbound SMS segment; inbound messages are not counted | | **Voice minutes** | Live + recorded call minutes per leg, rounded up to the nearest minute | ## Next steps Top up your balance or enable auto-recharge What happens at warning thresholds and after a downgrade # 10DLC Brand Registration Source: https://docs.bizzyco.ai/admin-guide/compliance/10dlc Register your business with The Campaign Registry so your US phone numbers can send SMS on carrier networks New US carriers require businesses that send SMS from local 10-digit numbers (10DLC) to register who they are. Unregistered traffic is filtered aggressively and can get a number blocked entirely. Registration starts with a **brand** — the verified identity of your business — which is reviewed by The Campaign Registry (TCR), the industry body that vets business senders. 10DLC compliance has two parts: the brand described here, and a messaging campaign registered against the brand that describes what you send. ## Before you register Have these details ready — they must match your official records, or verification will be rejected: * **Legal company name** exactly as it appears on your tax registration * **EIN** (US tax ID) — required for every entity type except sole proprietor * **Stock symbol and exchange** — required for publicly traded companies * A business email, phone number, and registered business address ## Register your brand 1. Go to **Purchases** and select **Brand Registration**. 2. Select **Register Brand**. 3. Fill in the business identity, contact, and address sections. For US addresses, use the 2-letter state code (for example, `TX`). 4. Select **Continue to review**, check the details, and complete checkout. Brand registration is a one-time fee shown on the review page. After payment, Bizzy submits your brand to the registry automatically. Verification typically completes within 1–3 business days, and the status on the Brand Registrations page updates as the registry reviews your submission. ## Registration statuses | Status | Meaning | | ------------------ | ------------------------------------------------------------------------------------------- | | **Pending review** | The brand was submitted and is being verified by the registry. | | **Verified** | Your business identity is confirmed. Approved and vetted brands also show as verified. | | **Rejected** | The registry could not verify the details. Check them against your records and re-register. | | **Suspended** | The registry suspended the brand. Contact support. | | **Failed** | The submission could not be processed. Register the brand again. | ## Troubleshooting * **Rejected after review** — The most common cause is a mismatch between the legal company name and the EIN on file with the IRS. Use the exact registered name, not a trade name. * **Status stuck on Pending review** — Registry review occasionally takes longer than 3 business days. The status updates automatically; no action is needed on your side. ## Next steps Purchase US local numbers for calling and texting Register an emergency address for outbound calling # E911 Emergency Addresses Source: https://docs.bizzyco.ai/admin-guide/compliance/e911 Register a validated emergency address so 911 dispatchers can locate callers using your US phone numbers New US local phone numbers used for outbound calling must have a registered E911 emergency address. When someone dials 911 from your number, this address is what emergency services see — and US carriers require it before a number can place outbound calls. Bizzy validates the address with the carrier and registers it for you. ## Which numbers need an emergency address | Number type | E911 required | | ---------------------- | -------------------------------------------------- | | US local | Yes — outbound calling is blocked until registered | | US toll-free | No — toll-free numbers cannot place E911 calls | | Non-US (CA, GB, AU, …) | No — E911 applies to US numbers only | Numbers that need an address but don't have one show an **Emergency address required** warning on the phone number page, and outbound voice stays blocked until registration completes. Inbound calls, voicemail, and SMS are not affected. ## Register an emergency address Prerequisites: a US local phone number purchased through Bizzy, and the physical street address where the number is used (not a PO box). 1. Go to **Phone Numbers** and open the number. 2. Select the **Emergency** tab. 3. Enter the business name, a contact name, and the street address. 4. Select **Validate & Register Address**. Bizzy first validates the address against the carrier's emergency-services database. If the address can't be validated, you'll see the error inline — often with a suggested correction (for example, a normalized street spelling or corrected ZIP code). Apply the suggestion and submit again. Once the address validates, Bizzy registers it with the carrier and enables emergency services on the number. Registration usually completes within a few minutes; the status updates automatically. ## Registration statuses | Status | Meaning | | -------------- | ----------------------------------------------------------------------------------- | | **Pending** | The address was submitted and the carrier is provisioning emergency services. | | **Registered** | Emergency services are active. Outbound calling is enabled for this number. | | **Failed** | Validation or provisioning failed. Review the error shown on the page and resubmit. | | **Disabled** | Emergency services were deprovisioned at the carrier. Re-register to restore them. | ## Update an emergency address If your business moves, update the address promptly — emergency responders are dispatched to the registered address. 1. Open the number's **Emergency** tab. 2. Edit the address fields. 3. Select **Validate & Update Address**. The new address goes through the same validation and registration flow. The previous registration stays active until the new one completes. ## Troubleshooting * **Validation keeps failing** — Use the exact street address (no PO boxes, mail drops, or vanity suite names). If a suggested address is shown, submit that version. * **Status stuck on Pending** — Carrier provisioning occasionally takes longer. The status updates automatically when the carrier confirms; no action is needed on your side. * **Registration failed** — The error from the carrier is shown on the Emergency tab. Correct the address and resubmit. If it persists, contact support. ## Next steps Purchase US local numbers for calling and texting Set SMS, voice, and voicemail options # Admin Guide Source: https://docs.bizzyco.ai/admin-guide/index Administer your Bizzy organization, billing, security, and integrations The Admin Guide covers everything you do as an account or organization admin: shape your team, run billing, secure access, and connect external services. ## Where to start Set up your organization, invite team members, and define roles Subscriptions, credits, usage tracking, and payment methods Passkeys, two-factor authentication, and API keys Connect Stripe and other external services ## Account-wide settings Configure in-app and email alerts for billing, usage, and integrations Name, avatar, timezone, language, and password ## Looking for something else? * End-user features (inbox, contacts, agents, automations) live in the [User Guide](/user-guide) * Programmatic access to Bizzy is in the [API Reference](/api-reference/introduction) * AI agent integration is covered in the [MCP Server](/mcp-server/introduction) docs # Integrations Source: https://docs.bizzyco.ai/admin-guide/integrations/index Connect external services to Bizzy Integrations let Bizzy exchange data with the systems you already use. Each integration is configured at the right scope — payments at the Business level, mailbox connections at the email-address level, and so on. ## Available integrations Sync customers and transactions between a Business and a Stripe account Connect Gmail or Microsoft 365 mailboxes for inbound and outbound email Verify or register domains used for sending email Provision phone numbers for SMS and voice Connecting a service usually requires the **Owner** or **Admin** role. Check each integration's page for specific requirements. # Stripe Connect Source: https://docs.bizzyco.ai/admin-guide/integrations/stripe Connect a Stripe account to a Business and sync customers and transactions into Bizzy Stripe Connect links a Stripe account to a Business in Bizzy so customers and transactions sync between the two systems. You configure it from your organization's settings — each Business can connect to one Stripe account. ## Prerequisites * You must be an **Owner** or **Admin** to connect, disconnect, or change sync settings * The Business you want to connect must already exist in Bizzy (see [Business profile](/user-guide/businesses)) * You need an existing Stripe account with permission to authorize OAuth connections ## Connect Stripe To connect a Business to Stripe: 1. Navigate to **Settings > Integrations > Stripe** (at `/{orgSlug}/settings/integrations/stripe`) 2. Click **Connect Stripe** 3. You're redirected to Stripe's authorization page — sign in if needed and approve the connection 4. Stripe sends you back to the integration page with a success message When the connection completes, Bizzy automatically: * Sets the sync mode to **One-Way** (Stripe → Bizzy) * Triggers an initial full inbound sync of customers and transactions The connected account's name, email, and connection date appear at the top of the page once linked. The first connection's initial sync runs in the background. Larger Stripe accounts may take several minutes; the page shows the most recent full-sync timestamp when complete. ## Sync modes Stripe Connect supports three sync modes. You can switch between them at any time without disconnecting. | Mode | Direction | What syncs | When | | ----------- | --------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | | **Off** | None | Nothing — connection stays linked but no data moves | N/A | | **One-Way** | Stripe → Bizzy | Customers, charges, invoices from Stripe | Real-time via webhooks; full sync on enable from Off (if >7 days stale) or via **Sync Now** | | **Two-Way** | Both directions | Inbound from Stripe (as One-Way) plus outbound: customer name, email, and phone edits in Bizzy push to Stripe | Inbound real-time; outbound triggered by edits in Bizzy | To change modes: 1. On the Stripe integration page, find the **Sync mode** card 2. Select the new mode 3. Confirm in the dialog that explains what will happen Switching to **Two-Way** does not bulk-push existing Bizzy customers to Stripe. Only future edits sync outbound. Inbound sync from Stripe remains complete in both One-Way and Two-Way. ### Manual full sync Use **Sync Now** on the integration page to re-run a full inbound sync without changing modes. This is useful after bulk changes in Stripe (e.g., importing customers there) or to recover from a long offline period. When sync mode was Off for more than 7 days and you re-enable it, Bizzy runs a full inbound sync automatically to catch up. ## Customer mapping Bizzy tries to link Stripe customers to existing Bizzy customers automatically by **normalized email address** during initial sync. The matching rules: | Result | Behavior | | ---------------------------------------- | -------------------------------------------------------------- | | Exactly one Bizzy customer matches | Auto-linked | | Multiple Bizzy customers share the email | Marked **ambiguous** — requires manual resolution | | No Bizzy customer matches | Left unlinked — a new customer is created on first transaction | ### Manage mappings Click **Manage Customer Mapping** on the Stripe integration page (or visit `/{orgSlug}/settings/integrations/stripe/customer-mapping`) to review and edit links. The customer-mapping table shows each Stripe customer alongside its current link status. Filter by **All**, **Unlinked**, **Ambiguous**, or **Linked** to focus on what needs attention. For each row you can: * **Link** — Open the customer picker, search Bizzy customers by name or email, and link manually * **Unlink** — Remove the existing link without deleting either customer * **Auto-link by email** — Bulk action at the top of the page; runs the same email-matching rule against all unlinked and ambiguous customers visible on the current page and reports a summary Pages of Stripe customers are pulled directly from Stripe's API with cursor-based pagination. Run the auto-link bulk action page-by-page if you have a large backlog. ## Sync errors When inbound or outbound sync fails for a specific customer or transaction, Bizzy records the error and surfaces it in a **Sync errors** card on the main integration page. Each error row shows: * The entity that failed * The error message * How many times it has been retried * The timestamp of the last attempt For each error you can click **Retry** to re-run the sync for that single entity. On success, the error row is removed; on failure, the attempt count increments. The **Clear all** button at the top of the card removes all error rows but **does not retry them**. Use it to acknowledge errors you've decided to ignore. ## Disconnecting To disconnect Stripe from a Business: 1. On the Stripe integration page, click **Disconnect Stripe** 2. Confirm in the dialog Disconnecting: * Stops all future inbound and outbound sync * Preserves all customers and transactions already imported into Bizzy * Leaves the Business in a clean state — you can connect a different Stripe account afterward ### Connection revoked from Stripe If you (or another Stripe admin) revoke Bizzy's access from the Stripe Dashboard directly, Bizzy detects the revocation the next time the integration page loads and shows a banner explaining the connection is no longer valid. Click the **Disconnect** button in the banner to clean up the broken connection record, then reconnect when ready. ## Limitations * **One Business per Stripe account.** Each Business connects to a single Stripe account; Stripe accounts cannot be shared across multiple Businesses * **Two-Way is forward-only.** Switching to Two-Way pushes future Bizzy edits to Stripe but does not back-fill historical edits * **Ambiguous matches require human review.** Auto-link skips any Stripe customer whose email matches multiple Bizzy customers * **Stripe rate limits.** Initial sync respects Stripe's per-account rate limits and throttles between pages, so very large accounts take longer than a single API page would suggest ## Next steps Work with synced customers in Bizzy Configure the Business that owns the Stripe connection # Notifications Source: https://docs.bizzyco.ai/admin-guide/notifications Receive in-app and email alerts for billing, usage, integrations, and system events Bizzy sends notifications about events that need your attention — billing failures, usage thresholds, lost integration connections, credit balance changes, and more. You receive each notification in the in-app bell and (optionally) by email; preferences are configurable per type and per channel. ## In-app bell The bell icon in the app header shows your unread count. Click it to open a panel with: * The most recent notifications, newest first, each with a relative timestamp ("2 hours ago", or absolute date for older items) * A blue dot next to unread items * A **Clear all** button at the top Clicking any notification marks it read immediately. Updates arrive in real time while the app is open — and if the live connection drops, the panel quietly falls back to periodic refreshes so you don't miss anything. ## Notification settings To change which notifications you receive and where: 1. Navigate to **Settings > User > Notifications** 2. Toggle individual notification types on or off per channel 3. Use **Unsubscribe from all emails** at the top to silence non-critical email globally — critical account-related messages (payment failures, security alerts) still send Settings are per-user; each team member configures their own. Two channels are available: **Web** (the in-app bell) and **Email**. ## Notification types Notifications are grouped by category, matching the settings UI: ### Domains | Notification | When you get it | | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Expiration warnings** | A registered domain is approaching expiration | | **Renewal succeeded** | A domain auto-renewal completed successfully | | **Renewal failed** | An automatic domain renewal failed | | **Renewal payment failed** | The payment for a domain renewal was declined | | **Registration succeeded** | A new domain registration completed | | **Registration failed** | A new domain registration could not complete | | **Registrant verification reminder** | A newly registered domain's ICANN registrant email verification deadline is approaching; sent even if you already verified — ignore it in that case | ### Email accounts | Notification | When you get it | | ------------------------- | --------------------------------------------------------------------------- | | **Connection lost** | A connected email account stopped syncing (token revoked, password changed) | | **Setup failed** | A new email account couldn't finish setup | | **Gmail connection lost** | Gmail-specific: a Google account's token expired or was revoked | ### Email sending | Notification | When you get it | | ------------------------- | ------------------------------------------------------------------------------------- | | **Setup started** | Sending-domain setup has begun | | **Verified** | A sending domain finished DNS verification | | **Verification failed** | A sending domain failed verification or timed out | | **Authentication broken** | A verified sending domain's SPF, DKIM, or DMARC records changed or stopped validating | ### Phone & voice | Notification | When you get it | | ------------------- | ---------------------------------------------- | | **Connection lost** | A connected number went offline at the carrier | | **Setup failed** | A new phone number couldn't finish setup | | **Call errors** | A live voice call ended with an error | ### Usage | Notification | When you get it | | --------------------------- | ----------------------------------------------------------------------- | | **Usage approaching limit** | A consumable reaches 90% of its monthly allowance | | **Usage limit reached** | A consumable reaches 100% of its allowance | | **Usage limit exceeded** | A consumable goes beyond 100% (overages now apply or service is paused) | ### Billing & payments | Notification | When you get it | | ----------------------------------------- | ---------------------------------------------------------------- | | **Payment failed** | A subscription or top-up payment was declined | | **Payment failed — 24 hour reminder** | A failed payment is still unresolved after 24 hours | | **Payment failed — final notice** | Final warning before the subscription is canceled for nonpayment | | **Subscription canceled — moved to Free** | The subscription was canceled and the account moved to Free | | **Plan changed or canceled** | You switched to a lower plan, or canceled your subscription | | **Trial started** | A new trial has started for your account | | **Trial ending soon** | Your trial ends in the next few days | | **Trial ended** | Your trial converted to paid or the account dropped to Free | ### Credits | Notification | When you get it | | --------------------------- | ------------------------------------------------------------------------ | | **Purchase successful** | A one-time credit purchase completed | | **Purchase failed** | A credit purchase attempt failed | | **Balance low** | Your credit balance dropped below the auto-recharge or default threshold | | **Balance depleted** | Your credit balance reached zero | | **Auto-recharge triggered** | An automatic credit top-up ran | ### System | Notification | When you get it | | ----------------- | -------------------------------------------------------------- | | **System errors** | An internal error affected your account and warrants attention | ## Critical notifications A subset of notifications always send by email regardless of your preferences: * Subscription and credit payment failures * Domain renewal payment failures * System errors These exist to make sure you can recover from situations that can interrupt service or lose data. ## Next steps Configure auto-recharge to head off low-balance alerts Track the consumption that drives usage notifications # Organization Source: https://docs.bizzyco.ai/admin-guide/organization/index Set up your organization, invite team members, and configure roles An **organization** is the workspace your team shares — contacts, agents, automations, businesses, and integrations all live inside it. One Bizzy account can own multiple organizations; team members and billing are tracked at the account level above. ## In this section Create an organization and configure its general and notification settings Invite, remove, and manage seats for your team Owner, Admin, and User capability matrix # Roles & Permissions Source: https://docs.bizzyco.ai/admin-guide/organization/permissions Understand how access control works in Bizzy Bizzy uses a role-based access control system to manage what team members can see and do within your organization. This guide explains the permission model and how to configure access for your team. ## Role Types Every organization member has one of three roles: | Role | Description | | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Owner** | Full access to all organization resources and settings. Can manage billing, API keys, and delete the organization. | | **Admin** | Full access to business data. Can invite members and manage integrations. Can view billing and subscription data but cannot modify the subscription or manage API keys. | | **User** | Read-only access to business data (contacts, messages, automations). Full access to their own user resources (files, preferences). Cannot access organization settings. | Each organization must have at least one Owner. Ownership can be transferred but not removed entirely. ## Permission Model Bizzy's permission system is built on three core concepts: ### 1. Actions Every permission check evaluates one of three actions: | Action | HTTP Methods | Description | | -------- | ---------------- | -------------------------- | | `read` | GET | View resources | | `write` | POST, PUT, PATCH | Create or modify resources | | `delete` | DELETE | Remove resources | ### 2. Resources Resources are organized hierarchically using dot notation. For example: ``` contacts contacts.emails contacts.phones contacts.tags ``` ### 3. Inheritance Permissions flow from parent to child resources. If you grant `read` access to `contacts`, that permission automatically applies to `contacts.emails`, `contacts.phones`, and all other child resources—unless explicitly overridden. ## Role Permissions ### Owner Permissions Owners have unrestricted access to all resources: | Resource Category | Read | Write | Delete | | ---------------------- | ---- | ----- | ------ | | Organization settings | Yes | Yes | Yes | | Members & invites | Yes | Yes | Yes | | API keys | Yes | Yes | Yes | | Billing & subscription | Yes | Yes | Yes | | All business data | Yes | Yes | Yes | ### Admin Permissions Admins have full data access with limited administrative capabilities: | Resource Category | Read | Write | Delete | | ---------------------- | ---- | ----- | ------ | | Organization settings | Yes | No | No | | Members | Yes | No | No | | Invites | Yes | Yes | Yes | | Connections | Yes | No | No | | Workflows | Yes | Yes | Yes | | API keys | No | No | No | | Billing & subscription | Yes | No | No | | Contacts & customers | Yes | Yes | Yes | | Messages | Yes | Yes | Yes | | Automations | Yes | Yes | Yes | | Files & folders | Yes | Yes | Yes | ### User Permissions Users have read-only access to organization data with full control over their own resources: | Resource Category | Read | Write | Delete | | ---------------------------------------- | ---- | ----- | ------ | | Organization settings | No | No | No | | Members & invites | No | No | No | | API keys | No | No | No | | Contacts, customers, businesses, domains | Yes | No | No | | Messages, automations, email templates | Yes | No | No | | Tasks | Yes | No | No | | RAG resources & embeddings | Yes | No | No | | Files & folders | Yes | Yes | No | | Own user profile | Yes | Yes | Yes | | Own notifications | Yes | Yes | Yes | ## Resource Categories The permission system covers these top-level resources: ### Contact and customer data * `contacts` — Contact records (children: `emails`, `phones`, `addresses`) * `customers` — Customer relationships (children: `transactions`) * `businesses` — Business entities (children: `offerings`, `onlinePresences`, `physicalPresences`, `profiles`) * `domains` — Verified and registered domains (children: `domainContacts`, `domainRegistrations`) ### Communication * `messages` — Conversation threads (children: `attachments`, `contacts`) * `incomingMessages` — Inbound message records (children: `attachments`, `contacts`) * `outgoingMessages` — Outbound message records (children: `attachments`, `contacts`) * `emailTemplates` — Reusable email templates ### Tasks and automations * `tasks` — Tasks (children: `assignees`, `activity`) * `automations` — Plain-English automations ### Files and knowledge * `files`, `folders` — Uploaded files and the folder tree * `resources`, `embeddings` — RAG-indexed assets used by agents ### Organization administration * `organization` — Org-level settings, with children: * `members` — Team membership * `invites` — Pending invitations * `connections` — Integration connections (Stripe, etc.) * `subscriptions` — Billing and subscription * `workflows` — Internal workflow registry * `apiKeys` — Owner-only API key management ### User-level resources * `userNotifications` — Personal notification preferences and history * `userProfiles` — Personal profile (name, avatar, timezone, language) ## API Key Permissions API keys have their own independent permission system — they do **not** inherit the permissions of the user that created them. When you create a key, you grant it specific resource access and restrict it to specific actions. This means a User-role team member can still create an API key with broader permissions than they themselves have, provided their role allows key creation in the first place (currently Owner-only). See [API Key Management](/admin-guide/security/api-keys) for details. ## Best Practices ### Principle of Least Privilege Assign the minimum role needed for each team member: * Use **User** role for team members who only need to view data * Use **Admin** role for managers who need to edit data and invite members * Reserve **Owner** role for account administrators ### Regular Access Reviews Periodically review your organization's members: * Remove inactive members promptly * Verify role assignments match current responsibilities * Check for any unused API keys ### Separation of Duties For sensitive operations, consider: * Limiting Owner role to 1-2 trusted administrators * Using separate API keys for different integrations * Enabling audit logging to track changes ## Next Steps Learn how to invite and manage team members Create API keys with custom permissions # Organization Setup Source: https://docs.bizzyco.ai/admin-guide/organization/setup Create and configure your Bizzy organization An organization is the primary workspace in Bizzy where your team collaborates on business communications. All data—contacts, messages, automations—is scoped to your organization. ## Creating an Organization When you sign up for Bizzy, you automatically create your first organization. Each organization includes: * **Name**: A display name for your organization (e.g., "Acme Corp") * **Slug**: A unique identifier used in URLs and API calls (auto-generated) * **Owner**: The user who created the organization (you) Your account tier determines how many organizations you can create. Most plans support a single organization, while enterprise tiers allow multiple organizations for managing separate business units. ## Organization Settings Access your organization settings from **Settings > Organization** in the dashboard. ### General Settings | Setting | Description | | ----------------- | ---------------------------------------------------------------------------- | | Organization Name | Display name shown throughout the app | | Slug | Unique identifier used in URLs and API references (read-only after creation) | | Time Zone | Default time zone for scheduling and reports | ### Notification Settings Configure which team members receive notifications for different event types. Notifications can be customized by role: * **Owner notifications**: Critical alerts, billing, security events * **Admin notifications**: Team changes, integration status, system alerts * **User notifications**: Assignment updates, task reminders ## Account Limits Your organization operates within your account's resource limits: | Resource | Description | | ------------- | ------------------------------------- | | Organizations | Number of organizations per account | | Seats | Maximum team members per organization | | Connections | Email provider connections | | API Keys | Active API keys | Contact support to upgrade your account limits or discuss enterprise options for multi-organization setups. ## Multi-Organization Support Enterprise accounts can create multiple organizations to: * Separate business units or brands * Isolate client data for agencies * Maintain development and production environments Each organization has its own: * Team members and roles * Email connections and integrations * Contacts, customers, and business data * API keys Users can belong to multiple organizations and switch between them from the account menu. ## Next Steps Invite team members to your organization Configure access control for your team # User Management Source: https://docs.bizzyco.ai/admin-guide/organization/users Invite, manage, and remove team members in your organization Manage who has access to your Bizzy organization by inviting team members, assigning roles, and controlling seat allocation. ## Prerequisites * You must be an **Owner** or **Admin** to manage users * Available seats in your organization ## Inviting Team Members To invite a new team member: 1. Navigate to **Settings > Organization > Members** 2. Click **Invite Member** 3. Enter the invitee's email address 4. Select a role: **Admin** or **User** (Owners cannot be invited—ownership must be transferred) 5. Click **Send Invite** The invitee receives an email with a unique invitation link. They must create a Bizzy account (or sign in to an existing one) to join your organization. Invitations expire after 7 days by default. You can resend or revoke invitations from the pending invites list. ### Invitation Statuses | Status | Description | | -------- | -------------------------------- | | Pending | Invite sent, awaiting acceptance | | Accepted | User has joined the organization | | Expired | Invite link has expired (7 days) | | Revoked | Invite was manually cancelled | ## Managing Team Members ### Viewing Members The Members page displays all organization members with: * Name and email * Role (Owner, Admin, User) * Join date * Status ### Changing Roles Only Owners can change member roles: 1. Find the member in the list 2. Click the role dropdown 3. Select the new role You cannot demote yourself. An organization must always have at least one Owner. ### Role Capabilities | Action | Owner | Admin | User | | --------------------------- | ----- | ----- | --------- | | View organization data | Yes | Yes | Yes | | Manage contacts & customers | Yes | Yes | Read-only | | Send messages | Yes | Yes | No | | Invite members | Yes | Yes | No | | Remove members | Yes | No | No | | Change member roles | Yes | No | No | | Manage API keys | Yes | No | No | | Billing & subscription | Yes | No | No | | Delete organization | Yes | No | No | See [Roles & Permissions](/admin-guide/organization/permissions) for detailed permission information. ## Removing Members Only Owners can remove members from the organization. To remove a member: 1. Navigate to **Settings > Organization > Members** 2. Find the member to remove 3. Click the **Remove** button (trash icon) 4. Confirm the removal Removing a member revokes their access immediately. Their data and activity history remain in the organization for audit purposes. ### What Happens When a Member is Removed * Immediate loss of organization access * Active sessions are terminated * Personal API keys are revoked * Email connections remain active (organization-owned) * Assigned tasks may need reassignment ## Seat Management Your organization has a maximum number of seats based on your subscription plan. ### Checking Seat Usage View your current seat allocation in **Settings > Organization > Members**: * **Used seats**: Active members * **Available seats**: Remaining capacity * **Pending invites**: Reserved but not yet accepted ### Seat Limits | Scenario | Behavior | | ------------------------ | --------------------------------------- | | At seat limit | Cannot send new invites | | Invite accepted at limit | Invite fails, user notified | | Member removed | Seat freed immediately | | Pending invite | Reserves a seat until expiry/revocation | To add more seats, upgrade your subscription plan in **Settings > Billing**. ## Transferring Ownership Organization ownership can be transferred to another Admin: 1. Navigate to **Settings > Organization > Members** 2. Find the Admin to promote 3. Click **Transfer Ownership** 4. Confirm the transfer After transfer: * The new Owner has full control * You become an Admin * This action cannot be undone without the new Owner's consent ## Next Steps Understand permission scopes for each role Create API keys for programmatic access # Send a user password reset Source: https://docs.bizzyco.ai/admin-guide/platform-admin/password-reset Help a Bizzy user recover access from the Platform Admin App New Use an admin-initiated password reset when a user cannot start the normal recovery flow themselves. This action sends the same one-time reset email as the public forgot-password flow. It does not reveal or directly set the user's password. ## Prerequisites * You need write-tier Platform Admin access * You need a typed reason for the request ## Send the reset email 1. In the Platform Admin App, open **Users** and select the user. 2. In **Actions**, select **Send password reset**. 3. Verify the displayed email address. 4. Enter the reason for the request. 5. Select **Send reset email**. The user receives a one-time link to Bizzy's existing change-password flow. Sending a reset email does not revoke the user's active sessions. Session revocation is not yet available in the Platform Admin App. ## Audit record After Bizzy queues the reset email, it attempts to add a `user.password_reset_initiated` audit record. If audit persistence fails, the reset email may still have been sent. When the record is stored, the main Platform Admin Audit Log shows its time, staff actor, action, target, and summary. The user-detail audit panel shows the same entry without a separate target column. The stored record also includes the typed reason and available request metadata, such as the request ID, IP address, and user agent. It always targets the user and includes an associated account only when one exists. # API Key Management Source: https://docs.bizzyco.ai/admin-guide/security/api-keys Create and manage API keys for programmatic access to Bizzy API keys allow external applications and scripts to access your Bizzy organization programmatically. This guide covers creating, configuring, and securing your API keys. This guide covers API keys for REST API access. AI agents (Claude, Cursor, Windsurf, etc.) connect through the [MCP server](/mcp-server/introduction), which uses its own authentication flow rather than API keys. ## Prerequisites * You must be an **Owner** to manage API keys * Admins and Users cannot create, view, or revoke API keys ## Creating an API Key To create a new API key: 1. Navigate to **Settings > Security > API Keys** 2. Click **Create API Key** 3. Enter a descriptive name (e.g., "Production CRM Integration") 4. Configure permissions (see below) 5. Optionally set an expiration date 6. Click **Create** The full API key is displayed only once after creation. Copy it immediately and store it securely. You cannot retrieve the full key later. ### API Key Format Bizzy API keys are prefixed with `sk_` followed by a long random secret: ``` sk_a1b2c3... ``` * `sk_` - Indicates a secret key * Followed by a unique random string For security, Bizzy stores only a hash of each key — never the key itself. After creation, the full key is shown once; the dashboard thereafter displays a masked preview (the `sk_` prefix plus the last four characters, e.g. `sk_a1b…c3d4`) so you can identify a key without exposing it. ## Setting Permissions API keys support fine-grained permissions that control which resources the key can access and what actions it can perform. ### Permission Structure Each permission specifies: | Component | Description | Example | | --------- | --------------------------- | ------------------------- | | Resource | What the key can access | `contacts`, `messages` | | Action | What operations are allowed | `read`, `write`, `delete` | ### Common Permission Patterns **Read-Only Access** ```json theme={null} { "contacts": { "read": true, "write": false, "delete": false }, "customers": { "read": true, "write": false, "delete": false } } ``` **Full Contact Management** ```json theme={null} { "contacts": { "read": true, "write": true, "delete": true } } ``` **Messaging Only** ```json theme={null} { "messages": { "read": true, "write": true, "delete": false } } ``` ### Permission Inheritance Permissions cascade to child resources. Granting access to `contacts` automatically includes: * `contacts.emails` * `contacts.phones` * `contacts.addresses` * `contacts.tags` * `contacts.notes` You can override child permissions to restrict access further. ## Key Expiration Set an expiration date to automatically disable API keys after a certain period: | Use Case | Recommended Expiration | | ----------------------- | ------------------------------- | | Temporary integrations | 7-30 days | | Contractor access | Project duration | | Production integrations | 90-365 days | | Internal tools | No expiration (rotate manually) | Expired keys return a `401 Unauthorized` error. Create a new key before the old one expires to avoid service interruption. ## Monitoring Key Usage Track API key activity from the API Keys dashboard: | Metric | Description | | --------- | ------------------------------------------------ | | Key | Masked preview (`sk_…last4`) to identify the key | | Last Used | Timestamp of the most recent API call | | Created | When the key was created | | Expires | Expiration date (if set) | | Status | Active, Expired, or Revoked | Use the "Last Used" timestamp to identify unused keys that should be revoked. ## Revoking Keys To revoke an API key: 1. Navigate to **Settings > Security > API Keys** 2. Find the key to revoke 3. Click **Revoke** 4. Confirm the action Revoked keys cannot be restored. Any application using the revoked key will immediately lose access. ### When to Revoke Revoke API keys immediately when: * A key may have been compromised * An employee with key access leaves the organization * An integration is decommissioned * A key hasn't been used in 90+ days ## Security Best Practices ### Key Storage * **Never** commit API keys to version control * Use environment variables or secret management services * Restrict file permissions on configuration files containing keys ```bash Environment Variable theme={null} export BIZZY_API_KEY="sk_live_abc123..." ``` ```typescript TypeScript theme={null} const apiKey = process.env.BIZZY_API_KEY; ``` ```python Python theme={null} import os api_key = os.environ.get('BIZZY_API_KEY') ``` ### Key Rotation Regularly rotate API keys to limit exposure from potential leaks: 1. Create a new key with the same permissions 2. Update your application to use the new key 3. Verify the new key works in production 4. Revoke the old key Recommended rotation schedule: | Environment | Rotation Frequency | | --------------- | ------------------ | | Production | Every 90 days | | Development | Every 30 days | | After incidents | Immediately | ### Principle of Least Privilege Grant only the permissions each integration needs: * Read-only keys for reporting and analytics * Resource-specific keys for focused integrations * Separate keys for separate applications ### Audit Regularly Review your API keys monthly: * Remove unused keys (no activity in 90+ days) * Verify permissions match current requirements * Check expiration dates and rotate as needed ## Troubleshooting ### Common Errors | Error | Cause | Solution | | ----------------------- | ------------------------ | --------------------------------------- | | `401 Unauthorized` | Invalid or expired key | Check key value and expiration | | `403 Forbidden` | Insufficient permissions | Verify key has required resource/action | | `429 Too Many Requests` | Rate limit exceeded | Implement backoff and retry logic | ### Debugging Permission Issues If your API key returns `403 Forbidden`: 1. Check the error response for the required permission 2. Compare against your key's configured permissions 3. Update the key or create a new one with correct permissions ## Next Steps Learn how to use the Bizzy API Understand API authentication methods # Data Protection Source: https://docs.bizzyco.ai/admin-guide/security/data-protection How Bizzy isolates, transmits, retains, and protects your business data This page summarizes how Bizzy handles your data — what's isolated, what's encrypted, what AI can and can't see, and how deletion works. For legal terms, see the [privacy policy](https://www.bizzyco.ai/privacy) and [data processing addendum](https://www.bizzyco.ai/dpa). ## Organization-level isolation Every record in Bizzy — contacts, messages, files, agents, automations — belongs to exactly one organization, and all access is scoped to it. Members of one organization can never see another organization's data, and agent retrieval enforces the same boundary on every query. See [Organizations](/get-started/concepts/organizations). ## Account security You control how your team signs in and what programmatic access exists: * [Passkeys](/admin-guide/security/passkeys) — phishing-resistant sign-in * [Two-factor authentication](/admin-guide/security/two-factor) — TOTP and backup codes * [API keys](/admin-guide/security/api-keys) — scoped per permission, and revocable at any time ## Encryption in transit All traffic between your browser (or API and MCP clients) and Bizzy is encrypted in transit over HTTPS/TLS. ## Connected email accounts Email accounts connect through **OAuth 2.0** — Bizzy never sees or stores your email password, and you can revoke access at any time from Bizzy or from your Google or Microsoft account settings. See [Connect Email](/user-guide/email/connect). ## What AI agents can access Agents operate inside your organization only, and within it you decide what they can touch: * **Files are invisible to agents by default.** A file is only retrievable after you turn on its **Agent access** flag; folders can be excluded wholesale. See [RAG Indexing](/user-guide/files/rag-indexing). * **Every action is permission-gated.** Each tool an agent can use is set to allow, ask, or deny — writes default to requiring your approval. See [Tool Permissions](/user-guide/agents/tool-permissions). * **Everything is auditable.** Full transcripts of every agent conversation, including tool calls and approvals, are retained for review. See [Transcripts](/user-guide/agent-conversations/transcripts). * **No training on your data.** Your data is not used to train foundation AI models. See the [AI disclosure](https://www.bizzyco.ai/ai-disclosure) for the providers involved and the full policy. ## Payments Subscription payments are processed by **Stripe**. Card details are entered into Stripe's secure payment elements and sent directly to Stripe — Bizzy never sees or stores card numbers. Stripe Connect syncs for your own customers work the same way: Bizzy reads customer and transaction records via Stripe's API and never handles raw card data. See [Stripe Connect](/admin-guide/integrations/stripe). ## Deletion and recovery Deleting records in Bizzy removes them from your view and from agent retrieval. Deletion is soft — data is retained for a period so accidental deletions can be recovered. There is no self-serve restore today; contact [support@bizzyco.ai](mailto:support@bizzyco.ai) to recover something. See [File Deletion](/user-guide/files/deletion). ## Reporting a vulnerability Report suspected security vulnerabilities to [support@bizzyco.ai](mailto:support@bizzyco.ai) and we'll prioritize the investigation. Please give us a chance to fix an issue before disclosing it publicly. ## Related pages Phishing-resistant sign-in TOTP and backup codes Scoped programmatic access Contact the team # Security Source: https://docs.bizzyco.ai/admin-guide/security/index Sign-in security, API keys, and how Bizzy protects your data Secure how your team signs in, control programmatic access, and understand how Bizzy protects your data. ## Sign-in security Phishing-resistant sign-in with device biometrics TOTP codes and backup codes ## Key Management Bizzy uses **API Keys** for REST API access from backend services, scripts, and integrations. API key management requires the **Owner** role. Create keys for REST API integrations AI agents (Claude, Cursor, Windsurf, etc.) connect through the [MCP server](/mcp-server/introduction), which uses its own authentication flow rather than API keys. ## Data protection Isolation, encryption in transit, AI data access, deletion and recovery ## Security Best Practices * **Principle of least privilege**: Grant only the permissions each key needs * **Separate keys per integration**: Create dedicated keys for each service or agent * **Regular audits**: Review and revoke unused keys monthly * **Secure storage**: Never commit keys to version control; use environment variables # Passkeys Source: https://docs.bizzyco.ai/admin-guide/security/passkeys Sign in with biometrics or a hardware key using WebAuthn passkeys Passkeys let you sign in to Bizzy without a password using your device's biometrics (Touch ID, Face ID, Windows Hello) or a hardware security key. Passkeys are phishing-resistant and don't require remembering or rotating a shared secret. ## Prerequisites * A device or browser that supports WebAuthn (every current major browser does) * A signed-in Bizzy account — passkeys are added to your existing account, not used to create one ## Add a passkey 1. Navigate to **Settings > User > Security** 2. In the **Passkeys** card, click **Add passkey** 3. Your browser prompts you to choose a device — phone biometric, platform authenticator (Touch ID / Windows Hello), or a security key 4. Complete the device prompt The new passkey appears in the list with an auto-generated name (`Passkey #1`, `Passkey #2`, etc.) and the date it was added. Add as many passkeys as you have devices — each one is registered to that specific device. You can register passkeys even if your account uses email-and-password sign-in. Passkeys are an additional sign-in method, not a replacement. ## Rename or delete a passkey In the **Passkeys** card: * Click the **pencil** icon to rename a passkey (max 64 characters) — useful for distinguishing "Work laptop" from "Personal phone" * Click the **trash** icon to delete a passkey, then confirm Deleted passkeys cannot be restored — register a new one if you need access from that device again. ## Sign in with a passkey On the sign-in page: * **Conditional UI (autofill).** If your browser supports it, your saved passkey appears as a sign-in option directly in the email field's autofill menu — pick it, complete the device prompt, and you're in * **Manual button.** Click **Sign in with a passkey** to invoke the device picker without typing your email You can sign in with a passkey from any device that has one registered to your account. ## Limitations * **Last-used timestamp not yet tracked.** The passkey list shows the date a passkey was added but not when it was last used to sign in * **Per-device.** Passkeys are bound to the device that created them and don't sync across browsers unless you use a synced passkey provider (iCloud Keychain, Google Password Manager, 1Password, etc.) ## Next steps Add an extra factor with TOTP and backup codes Programmatic access for external integrations # Two-factor authentication Source: https://docs.bizzyco.ai/admin-guide/security/two-factor Protect your account with TOTP codes and recovery backup codes Two-factor authentication (2FA) requires a one-time code from an authenticator app each time you sign in. Bizzy uses TOTP (time-based one-time passwords), the same standard used by Google Authenticator, 1Password, Authy, and most other authenticator apps. ## Prerequisites * A signed-in Bizzy account with email-and-password sign-in (your password is required to enable 2FA) * An authenticator app installed on your phone or password manager ## Enable two-factor authentication 1. Navigate to **Settings > User > Security** 2. In the **Two-factor authentication** card, click **Enable two-factor authentication** 3. Enter your current password to confirm 4. Scan the displayed QR code with your authenticator app — or enter the secret manually if you can't scan 5. Enter the 6-digit code your app generates to verify the setup 6. Save the **backup codes** displayed on the next screen, then click **Done** Backup codes are shown **only once**. Save them in a password manager or other secure location before clicking Done. You'll need them if you ever lose access to your authenticator app. ### Backup codes Each backup code can be used once in place of a TOTP code. Use them when you don't have your authenticator app handy — for example, after losing or wiping a phone. To generate a fresh set: 1. In the **Two-factor authentication** card, click **Regenerate backup codes** 2. Enter your current password 3. Save the new codes — the previous set is invalidated immediately ## Sign in with two-factor authentication When 2FA is enabled, sign-in requires two steps: 1. Enter your email and password 2. Enter the 6-digit code from your authenticator app (or a one-time backup code) You're prompted on every new session — existing sessions stay valid until they expire normally. ## Disable two-factor authentication 1. Navigate to **Settings > User > Security** 2. In the **Two-factor authentication** card, click **Disable 2FA** 3. Enter your current password to confirm Disabling clears your TOTP secret and all unused backup codes. ## Limitations * **Self-serve only.** 2FA is per-user; Bizzy does not yet support organization-wide 2FA enforcement * **Active sessions list not yet available.** You can't currently view or revoke individual signed-in sessions from the security settings page — clearing browser cookies or changing your password ends all sessions ## Recovering a locked-out account If you've lost access to both your authenticator app and your backup codes, contact support — there is no self-serve path to disable 2FA without one of those factors. ## Next steps Sign in with biometrics or a hardware key Programmatic access for integrations # User profile Source: https://docs.bizzyco.ai/admin-guide/user-profile Manage your name, avatar, timezone, and language preferences Your user profile is per-account, not per-organization — settings here apply everywhere you sign in. Each team member maintains their own profile. ## Where to find it Navigate to **Settings > User > Profile**. ## Editable fields | Field | Notes | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Profile picture** | Upload JPG, PNG, GIF, or WebP up to 10 MB. Drag-and-drop or pick from disk. Used in @-mentions, comments, and the team-members list | | **First name** | Optional, free-form | | **Last name** | Optional, free-form | | **Timezone** | IANA timezone (e.g., `America/Los_Angeles`). Determines display of timestamps across the app. Defaults to `America/Los_Angeles` | | **Language** | UI language. Currently supported: English (en), Spanish (es), French (fr), German (de), Italian (it), Japanese (ja), Korean (ko), Chinese (zh), Portuguese (pt), Russian (ru), Arabic (ar), Hindi (hi). Defaults to `en` | Changes save when you click **Save** at the bottom of the form. Language affects the web UI only. Email content and AI agent output use the locale they were authored in. ## Change your password Password changes live on the security settings page, not the profile page. 1. Navigate to **Settings > User > Security** 2. In the **Password** card, enter your current password 3. Enter and confirm a new password 4. Click **Update password** Password requirements: at least 8 characters with at least one uppercase letter, one lowercase letter, and one number. This option is only visible if your account uses email-and-password sign-in. Accounts that sign in only with a third-party provider (Google, Microsoft) manage credentials at the provider. ## Email verification Your email address is verified when you first sign up: 1. Click the verification link in the email Bizzy sends after signup 2. You're automatically signed in after verification If you didn't receive the email, request a new one from the sign-in page. ## Account deletion Self-serve account deletion isn't currently available — contact support to delete your account and associated data. ## Next steps Configure how you receive alerts Add 2FA to your account # Docs MCP server Source: https://docs.bizzyco.ai/agent-resources/docs-mcp Mintlify-hosted MCP server for these docs. # llms.txt Source: https://docs.bizzyco.ai/agent-resources/llms Index of these docs in the llms.txt format. # llms-full.txt Source: https://docs.bizzyco.ai/agent-resources/llms-full Full body of these docs in the llms.txt format. # MCP server Source: https://docs.bizzyco.ai/agent-resources/mcp Connect AI agents to your Bizzy organization. # Authentication Source: https://docs.bizzyco.ai/api-reference/authentication Learn how to authenticate with the Bizzy API The Bizzy API uses API keys to authenticate requests. You can create and manage API keys from your organization settings in the dashboard. ## Creating an API Key 1. Sign in to the [Bizzy Dashboard](https://www.bizzyco.ai/home) 2. Navigate to **Settings** > **API Keys** 3. Click **Create API Key** 4. Give your key a descriptive name (e.g., "Production Server" or "Development") 5. Select the permission scopes your key needs 6. Click **Create** and copy your key immediately Your API key is only shown once when created. Store it securely - you won't be able to see it again. If you lose your key, you'll need to create a new one. ## Using Your API Key Include your API key in the `Authorization` header of every request using the Bearer token format: ``` Authorization: Bearer your-api-key ``` ```bash cURL theme={null} curl https://api.bizzyco.ai/v1/contacts \ -H "Authorization: Bearer sk_live_abc123..." ``` ```typescript TypeScript theme={null} const response = await fetch('https://api.bizzyco.ai/v1/contacts', { headers: { Authorization: 'Bearer sk_live_abc123...', }, }); const { data } = await response.json(); ``` ```python Python theme={null} import requests response = requests.get( 'https://api.bizzyco.ai/v1/contacts', headers={ 'Authorization': 'Bearer sk_live_abc123...', } ) data = response.json()['data'] ``` ## Permission Scopes API keys are scoped to specific permissions that control what resources they can access. When creating a key, grant only the permissions your integration needs. ### Available Scopes | Resource | Actions | Description | | -------------- | ------------------- | ---------------------------------------- | | `contacts` | read, write, delete | Manage contacts and their details | | `customers` | read, write, delete | Manage customer records | | `businesses` | read, write, delete | Manage business profiles | | `messages` | read, write, delete | Access email, SMS, and voice messages | | `automations` | read, write, delete | Configure automation workflows | | `domains` | read, write, delete | Manage custom domains | | `users` | read, write, delete | Manage user profiles and settings | | `organization` | read, write, delete | Manage organization settings and members | | `api_keys` | read, write, delete | Manage API keys and their permissions | | `resources` | read, write, delete | Access shared resources and analytics | ### Permission Inheritance Permissions follow a hierarchical model. Granting access to a parent resource also grants access to its child resources: * `contacts` includes `contacts.emails`, `contacts.phones`, `contacts.addresses`, `contacts.tags`, `contacts.notes` * `customers` includes `customers.contacts` * `businesses` includes `businesses.details`, `businesses.tags`, `businesses.contacts`, `businesses.addresses` * `messages` includes `messages.email`, `messages.sms`, `messages.voice` * `automations` includes `automations.actions` * `domains` includes `domains.dns`, `domains.verification` * `users` includes `users.profile`, `users.settings` * `organization` includes `organization.settings`, `organization.billing` * `resources` includes `resources.analytics` ### HTTP Methods and Permissions | HTTP Method | Required Permission | | ----------- | ------------------- | | GET | `read` | | POST | `write` | | PUT, PATCH | `write` | | DELETE | `delete` | ## Authentication Errors If authentication fails, you'll receive a `401 Unauthorized` response: ```json theme={null} { "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key" } } ``` Common causes: * Missing `Authorization` header * Invalid or revoked API key * Malformed Bearer token (missing "Bearer " prefix) If your key lacks permission for a specific action, you'll receive a `403 Forbidden` response: ```json theme={null} { "error": { "code": "INSUFFICIENT_PERMISSIONS", "message": "Missing write permission for contacts", "details": { "required": { "resource": "contacts", "action": "write" }, "hint": "Contact your administrator to request additional permissions" } } } ``` ## Security Best Practices Use environment variables or a secrets manager to store your API keys. Add `.env` files to your `.gitignore`. ```bash theme={null} # .env (never commit this file) BIZZY_API_KEY=sk_live_abc123... ``` ```typescript theme={null} // Use environment variables const apiKey = process.env.BIZZY_API_KEY; ``` Create different API keys for development, staging, and production. This limits the blast radius if a key is compromised. Follow the principle of least privilege. Only grant the specific permissions your integration needs. A read-only dashboard doesn't need write access. Periodically create new API keys and deprecate old ones. This limits the window of exposure if a key is leaked. Review your API key activity in the dashboard regularly. Revoke any keys showing suspicious activity immediately. ## Server-Side Only API keys should only be used in server-side code. Never expose your API key in client-side JavaScript, mobile apps, or any code that runs in the browser. If you need to access the Bizzy API from a client application, implement a backend proxy that handles authentication on behalf of your users. # Get automation execution Source: https://docs.bizzyco.ai/api-reference/automation-executions/get-automation-execution /api-reference/openapi.json get /v1/automations/{id}/executions/{executionId} Get a specific execution for an automation # List automation executions Source: https://docs.bizzyco.ai/api-reference/automation-executions/list-automation-executions /api-reference/openapi.json get /v1/automations/{id}/executions List all executions for a specific automation with pagination # Create automation Source: https://docs.bizzyco.ai/api-reference/automations/create-automation /api-reference/openapi.json post /v1/automations Create a new automation # Delete automation Source: https://docs.bizzyco.ai/api-reference/automations/delete-automation /api-reference/openapi.json delete /v1/automations/{id} Delete an automation (soft delete) # Get automation Source: https://docs.bizzyco.ai/api-reference/automations/get-automation /api-reference/openapi.json get /v1/automations/{id} Get a specific automation by ID # List automations Source: https://docs.bizzyco.ai/api-reference/automations/list-automations /api-reference/openapi.json get /v1/automations List all automations with pagination support # Partially update automation Source: https://docs.bizzyco.ai/api-reference/automations/partially-update-automation /api-reference/openapi.json patch /v1/automations/{id} Partially update an existing automation. Only provided fields will be updated. # Update automation Source: https://docs.bizzyco.ai/api-reference/automations/update-automation /api-reference/openapi.json put /v1/automations/{id} Update an existing automation. Note: This endpoint accepts partial updates (same behavior as PATCH). All fields are optional. # Create business offering Source: https://docs.bizzyco.ai/api-reference/business-offerings/create-business-offering /api-reference/openapi.json post /v1/businesses/{id}/offerings Create a new offering for a business # Delete business offering Source: https://docs.bizzyco.ai/api-reference/business-offerings/delete-business-offering /api-reference/openapi.json delete /v1/businesses/{id}/offerings/{offeringId} Delete an offering from a business # Get business offering Source: https://docs.bizzyco.ai/api-reference/business-offerings/get-business-offering /api-reference/openapi.json get /v1/businesses/{id}/offerings/{offeringId} Get a specific offering for a business # List business offerings Source: https://docs.bizzyco.ai/api-reference/business-offerings/list-business-offerings /api-reference/openapi.json get /v1/businesses/{id}/offerings List all offerings for a specific business with pagination # Update business offering Source: https://docs.bizzyco.ai/api-reference/business-offerings/update-business-offering /api-reference/openapi.json put /v1/businesses/{id}/offerings/{offeringId} Update an existing offering for a business # Create business online presence Source: https://docs.bizzyco.ai/api-reference/business-online-presences/create-business-online-presence /api-reference/openapi.json post /v1/businesses/{id}/online-presences Create a new online presence for a business # Delete business online presence Source: https://docs.bizzyco.ai/api-reference/business-online-presences/delete-business-online-presence /api-reference/openapi.json delete /v1/businesses/{id}/online-presences/{onlinePresenceId} Delete an online presence from a business # Get business online presence Source: https://docs.bizzyco.ai/api-reference/business-online-presences/get-business-online-presence /api-reference/openapi.json get /v1/businesses/{id}/online-presences/{onlinePresenceId} Get a specific online presence for a business # List business online presences Source: https://docs.bizzyco.ai/api-reference/business-online-presences/list-business-online-presences /api-reference/openapi.json get /v1/businesses/{id}/online-presences List all online presences for a specific business with pagination # Update business online presence Source: https://docs.bizzyco.ai/api-reference/business-online-presences/update-business-online-presence /api-reference/openapi.json put /v1/businesses/{id}/online-presences/{onlinePresenceId} Update an existing online presence for a business # Create business physical presence Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/create-business-physical-presence /api-reference/openapi.json post /v1/businesses/{id}/physical-presences Create a new physical presence for a business # Delete business physical presence Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/delete-business-physical-presence /api-reference/openapi.json delete /v1/businesses/{id}/physical-presences/{physicalPresenceId} Delete a physical presence from a business # Get business physical presence Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/get-business-physical-presence /api-reference/openapi.json get /v1/businesses/{id}/physical-presences/{physicalPresenceId} Get a specific physical presence for a business # List business physical presences Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/list-business-physical-presences /api-reference/openapi.json get /v1/businesses/{id}/physical-presences List all physical presences for a specific business with pagination # Update business physical presence Source: https://docs.bizzyco.ai/api-reference/business-physical-presences/update-business-physical-presence /api-reference/openapi.json put /v1/businesses/{id}/physical-presences/{physicalPresenceId} Update an existing physical presence for a business # Get business profile Source: https://docs.bizzyco.ai/api-reference/business-profile/get-business-profile /api-reference/openapi.json get /v1/businesses/{id}/profile Get the profile for a specific business # Update business profile Source: https://docs.bizzyco.ai/api-reference/business-profile/update-business-profile /api-reference/openapi.json put /v1/businesses/{id}/profile Update the profile for a business # Get business Source: https://docs.bizzyco.ai/api-reference/businesses/get-business /api-reference/openapi.json get /v1/businesses/{id} Get a specific business by ID # List businesses Source: https://docs.bizzyco.ai/api-reference/businesses/list-businesses /api-reference/openapi.json get /v1/businesses List all businesses with pagination support # Partially update business Source: https://docs.bizzyco.ai/api-reference/businesses/partially-update-business /api-reference/openapi.json patch /v1/businesses/{id} Partially update an existing business. Only provided fields will be updated. # Update business Source: https://docs.bizzyco.ai/api-reference/businesses/update-business /api-reference/openapi.json put /v1/businesses/{id} Update an existing business. Note: This endpoint accepts partial updates (same behavior as PATCH). # Create contact address Source: https://docs.bizzyco.ai/api-reference/contact-addresses/create-contact-address /api-reference/openapi.json post /v1/contacts/{id}/addresses Create a new address for a contact # Delete contact address Source: https://docs.bizzyco.ai/api-reference/contact-addresses/delete-contact-address /api-reference/openapi.json delete /v1/contacts/{id}/addresses/{addressId} Delete an address from a contact # Get contact address Source: https://docs.bizzyco.ai/api-reference/contact-addresses/get-contact-address /api-reference/openapi.json get /v1/contacts/{id}/addresses/{addressId} Get a specific address for a contact # List contact addresses Source: https://docs.bizzyco.ai/api-reference/contact-addresses/list-contact-addresses /api-reference/openapi.json get /v1/contacts/{id}/addresses List all addresses for a specific contact with pagination # Update contact address Source: https://docs.bizzyco.ai/api-reference/contact-addresses/update-contact-address /api-reference/openapi.json put /v1/contacts/{id}/addresses/{addressId} Update an existing address for a contact # Create contact email Source: https://docs.bizzyco.ai/api-reference/contact-emails/create-contact-email /api-reference/openapi.json post /v1/contacts/{id}/emails Create a new email for a contact # Delete contact email Source: https://docs.bizzyco.ai/api-reference/contact-emails/delete-contact-email /api-reference/openapi.json delete /v1/contacts/{id}/emails/{emailId} Delete an email from a contact # List contact emails Source: https://docs.bizzyco.ai/api-reference/contact-emails/list-contact-emails /api-reference/openapi.json get /v1/contacts/{id}/emails List all emails for a specific contact with pagination # Update contact email Source: https://docs.bizzyco.ai/api-reference/contact-emails/update-contact-email /api-reference/openapi.json put /v1/contacts/{id}/emails/{emailId} Update an existing email for a contact # Create contact phone number Source: https://docs.bizzyco.ai/api-reference/contact-phone-numbers/create-contact-phone-number /api-reference/openapi.json post /v1/contacts/{id}/phone-numbers Create a new phone number for a contact # Delete contact phone number Source: https://docs.bizzyco.ai/api-reference/contact-phone-numbers/delete-contact-phone-number /api-reference/openapi.json delete /v1/contacts/{id}/phone-numbers/{phoneNumberId} Delete a phone number from a contact # List contact phone numbers Source: https://docs.bizzyco.ai/api-reference/contact-phone-numbers/list-contact-phone-numbers /api-reference/openapi.json get /v1/contacts/{id}/phone-numbers List all phone numbers for a specific contact with pagination # Update contact phone number Source: https://docs.bizzyco.ai/api-reference/contact-phone-numbers/update-contact-phone-number /api-reference/openapi.json put /v1/contacts/{id}/phone-numbers/{phoneNumberId} Update an existing phone number for a contact # Create contact Source: https://docs.bizzyco.ai/api-reference/contacts/create-contact /api-reference/openapi.json post /v1/contacts Create a new contact # Delete contact Source: https://docs.bizzyco.ai/api-reference/contacts/delete-contact /api-reference/openapi.json delete /v1/contacts/{id} Delete a contact (soft delete) # Get contact Source: https://docs.bizzyco.ai/api-reference/contacts/get-contact /api-reference/openapi.json get /v1/contacts/{id} Get a specific contact by ID with full details # List contacts Source: https://docs.bizzyco.ai/api-reference/contacts/list-contacts /api-reference/openapi.json get /v1/contacts List all contacts with full details and pagination support # Partially update contact Source: https://docs.bizzyco.ai/api-reference/contacts/partially-update-contact /api-reference/openapi.json patch /v1/contacts/{id} Partially update an existing contact. Only provided fields will be updated. # Update contact Source: https://docs.bizzyco.ai/api-reference/contacts/update-contact /api-reference/openapi.json put /v1/contacts/{id} Update an existing contact. Note: This endpoint accepts partial updates (same behavior as PATCH). # Create customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/create-customer-transaction /api-reference/openapi.json post /v1/customers/{id}/transactions Create a new transaction for a customer # Delete customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/delete-customer-transaction /api-reference/openapi.json delete /v1/customers/{id}/transactions/{transactionId} Delete a specific transaction for a customer (soft delete) # Get customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/get-customer-transaction /api-reference/openapi.json get /v1/customers/{id}/transactions/{transactionId} Get a specific transaction for a customer # List customer transactions Source: https://docs.bizzyco.ai/api-reference/customer-transactions/list-customer-transactions /api-reference/openapi.json get /v1/customers/{id}/transactions List all transactions for a specific customer with pagination # Partially update customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/partially-update-customer-transaction /api-reference/openapi.json patch /v1/customers/{id}/transactions/{transactionId} Partially update a specific transaction for a customer. Only provided fields will be updated. # Update customer transaction Source: https://docs.bizzyco.ai/api-reference/customer-transactions/update-customer-transaction /api-reference/openapi.json put /v1/customers/{id}/transactions/{transactionId} Update a specific transaction for a customer. Note: This endpoint accepts partial updates (same behavior as PATCH). All fields are optional. # Create customer Source: https://docs.bizzyco.ai/api-reference/customers/create-customer /api-reference/openapi.json post /v1/customers Create a new customer # Delete customer Source: https://docs.bizzyco.ai/api-reference/customers/delete-customer /api-reference/openapi.json delete /v1/customers/{id} Delete a customer (soft delete) # Get customer Source: https://docs.bizzyco.ai/api-reference/customers/get-customer /api-reference/openapi.json get /v1/customers/{id} Get a specific customer by ID # List customers Source: https://docs.bizzyco.ai/api-reference/customers/list-customers /api-reference/openapi.json get /v1/customers List all customers with pagination support # Partially update customer Source: https://docs.bizzyco.ai/api-reference/customers/partially-update-customer /api-reference/openapi.json patch /v1/customers/{id} Partially update an existing customer. Only provided fields will be updated. # Update customer Source: https://docs.bizzyco.ai/api-reference/customers/update-customer /api-reference/openapi.json put /v1/customers/{id} Update an existing customer. Note: This endpoint accepts partial updates (same behavior as PATCH). All fields are optional. # Register a Domain via the API Source: https://docs.bizzyco.ai/api-reference/domain-registration Search, quote, purchase, and track a new domain registration using the Bizzy REST API New Use the domain registration API when you want to buy a new domain programmatically through Bizzy. The API searches registrar availability, returns a live quote, charges your account's default saved Stripe payment method, and starts a registration operation you can poll until it completes. Availability checks are provider-backed, with Bizzy routing through its configured availability providers before returning the same response shape shown below. ## Prerequisites Before you call the registration endpoints, make sure you have: * A Bizzy API key with `domains:read` and `domains:write`. * A default Stripe payment method saved on the Bizzy account. * The registrant contact details required by the domain registry. * A maximum price, in cents, that you are willing to pay for the registration. The examples below use this base URL: ```bash theme={null} https://api.bizzyco.ai/v1 ``` ## Step 1: Search availability Search the exact domain you want to register. ```bash theme={null} curl "https://api.bizzyco.ai/v1/domain-registrations/search?query=example.com" \ -H "Authorization: Bearer $BIZZY_API_KEY" ``` The response is wrapped in `data`: ```json theme={null} { "data": { "query": "example.com", "results": [ { "domain": "example.com", "available": true, "premium": false, "registrationPriceCents": 1800, "renewalPriceCents": 1800 } ] } } ``` `registrationPriceCents` is the all-in first-year price and `renewalPriceCents` is the all-in per-year renewal price, both in USD cents. They can differ — premium domains in particular often renew at a different price than they register at. Both are `null` when the domain is unavailable. Only continue if `available` is `true`. ## Step 2: Get a live quote Request a quote for the domain and registration period. `periodYears` is optional and defaults to `1`; it can be any integer from `1` to `10`. ```bash theme={null} curl "https://api.bizzyco.ai/v1/domain-registrations/quote?domain=example.com&periodYears=1" \ -H "Authorization: Bearer $BIZZY_API_KEY" ``` Use the returned `amountCents` as the minimum value for `maxAmountCents` in the registration request. ```json theme={null} { "data": { "domain": "example.com", "available": true, "periodYears": 1, "amountCents": 1800, "currency": "usd", "premium": false, "registrationPriceCents": 1800, "renewalPriceCents": 1800 } } ``` `amountCents` is the all-in total you'll be charged: the first year at `registrationPriceCents` plus each additional year at `renewalPriceCents`. There are no other fees — WHOIS privacy is included at no extra cost. Quotes are live. The registration request re-checks availability and price before charging. If the current price is higher than `maxAmountCents`, the API rejects the request instead of charging you. ## Step 3: Register the domain Submit the registration request with the domain, price guardrail, registration settings, and registrant contact details. Registration moves money, so it requires an `Idempotency-Key` header. Generate a unique value per registration attempt and send the **same** value if you retry that attempt. ```bash theme={null} curl -X POST "https://api.bizzyco.ai/v1/domain-registrations" \ -H "Authorization: Bearer $BIZZY_API_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 9f8c2b1a-4d3e-4a6b-8c1d-2e3f4a5b6c7d" \ -d '{ "domain": "example.com", "periodYears": 1, "maxAmountCents": 1800, "autoRenew": true, "whoisPrivacy": true, "contact": { "label": "Primary registrant", "firstName": "Ada", "lastName": "Lovelace", "organizationName": "Example Co", "jobTitle": "Founder", "address1": "123 Market St", "address2": "Suite 400", "city": "San Francisco", "stateProvince": "CA", "postalCode": "94105", "country": "US", "email": "domains@example.com", "phone": "+14155550123" } }' ``` Successful registration requests return `202 Accepted` with an operation ID: ```json theme={null} { "data": { "operationId": "550e8400-e29b-41d4-a716-446655440000", "status": "queued", "domain": "example.com" } } ``` The API charges the account's default saved Stripe payment method before the operation is queued. If no default payment method exists, the request fails with `402`. ### Idempotency The `Idempotency-Key` header is required and makes the charge safe to retry: * **Reuse the same key** to retry a request that may already have succeeded (a timeout or dropped connection before you saw the `202`). The API replays the original operation and never charges twice. * **Use a new key** for a genuinely new registration attempt — for example, after a previous attempt failed and was refunded. If you omit the header, the request is rejected with `400`. The same header is required on domain renewal (`POST /v1/domains/{id}/registration/renew`). ## Required registration inputs | Field | Required | Notes | | ---------------- | -------- | ---------------------------------------------------------- | | `domain` | Yes | Domain name to register, such as `example.com` | | `periodYears` | No | Integer from `1` to `10`; defaults to `1` | | `maxAmountCents` | Yes | Maximum amount you authorize Bizzy to charge, in USD cents | | `autoRenew` | No | Defaults to `true` | | `whoisPrivacy` | No | Defaults to `true` | | `contact` | Yes | Registrant contact object used for the domain registration | Transfer lock is enabled automatically after a domain is registered. Manage it afterwards with `PATCH /v1/domains/{id}/registration`. The `contact` object requires: | Field | Required | Notes | | --------------- | -------- | ------------------------------------------ | | `firstName` | Yes | Registrant first name | | `lastName` | Yes | Registrant last name | | `address1` | Yes | Street address | | `city` | Yes | City | | `stateProvince` | Yes | State, province, or administrative region | | `postalCode` | Yes | Postal or ZIP code | | `country` | Yes | Two-letter country code, such as `US` | | `email` | Yes | Registrant email address | | `phone` | Yes | Registrant phone number; E.164 recommended | These contact fields are optional: `label`, `organizationName`, `jobTitle`, and `address2`. If you provide `organizationName`, `jobTitle` is also required — the domain registry rejects a company contact without a job title. `label` is stored only in Bizzy; changing it later does not update the registrar contact. After registration, update registrar-backed contact fields with `PATCH /v1/domains/{id}/registration/contact`. Changing the registrant's name, organization, or email resets Bizzy's 15-day ICANN verification window and shows the registrant verification notice again. Changing only the local `label` does not contact the registrar or reset verification. Registered Bizzy-managed domains can be deleted with `DELETE /v1/domains/{id}` only after the registration has fully lapsed: the domain's status must be `expired`, and its DNS zone must hold no records beyond the zone's built-in ones (the apex NS set and SOA). Disable email for the domain first so Bizzy removes the email records it manages, and delete any remaining records with the DNS record endpoints. A renewal that is already queued or running also blocks the deletion until it finishes. A blocked deletion returns `409` with code `REGISTERED_DOMAIN_NOT_EXPIRED`, `REGISTERED_DOMAIN_RENEWAL_IN_FLIGHT`, or `REGISTERED_DOMAIN_DNS_NOT_EMPTY` — the last lists the blocking records in the error details. This keeps a paid, still-active registration from being hidden from Bizzy while the registrar continues to renew it. ## Step 4: Poll the operation Registration is asynchronous because it depends on payment, registrar, DNS, and email setup work. Poll the operation until it reaches `succeeded` or `failed`. ```bash theme={null} curl "https://api.bizzyco.ai/v1/operations/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer $BIZZY_API_KEY" ``` Operation statuses are: | Status | Meaning | | ----------- | --------------------------------------------- | | `queued` | Payment succeeded and provisioning is waiting | | `running` | Registration provisioning has started | | `succeeded` | The domain was registered and added to Bizzy | | `failed` | Registration failed; check `errorMessage` | When the operation succeeds, `resourceType` is `domain` and `resourceId` is the new Bizzy domain ID. ```json theme={null} { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "domain_registration", "status": "succeeded", "resourceType": "domain", "resourceId": "6f5b6fc6-7e21-4f5b-8d6d-0c0f6c269b5d", "resourceName": "example.com", "workflowId": "domain-registration-example-com", "paymentIntentId": "pi_123", "errorCode": null, "errorMessage": null, "completedAt": "2026-06-14T16:30:00.000Z", "createdAt": "2026-06-14T16:29:45.000Z", "updatedAt": "2026-06-14T16:30:00.000Z" } } ``` ## Step 5: Read the domain After the operation succeeds, fetch the new domain using `resourceId`. ```bash theme={null} curl "https://api.bizzyco.ai/v1/domains/6f5b6fc6-7e21-4f5b-8d6d-0c0f6c269b5d" \ -H "Authorization: Bearer $BIZZY_API_KEY" ``` Registered domains are managed by Bizzy, so DNS and email authentication records are configured automatically. The domain becomes usable for Bizzy-hosted email after setup completes. ## Common failures | Error code | HTTP status | What to do | | ------------------------- | ----------- | -------------------------------------------------------------- | | `DOMAIN_UNAVAILABLE` | `409` | Search for another domain or TLD | | `PRICE_EXCEEDS_MAXIMUM` | `409` | Get a fresh quote and decide whether to raise `maxAmountCents` | | `PAYMENT_METHOD_REQUIRED` | `402` | Add or choose a default payment method in Bizzy billing | | `PAYMENT_FAILED` | `402` | Update the default payment method and try again | ## Next steps After registration succeeds: * Create an email address on the domain from [Bizzy-hosted email addresses](/user-guide/email-addresses/bizzy-hosted). * Manage records with the [`/v1/domains/{id}/dns-records`](/user-guide/domains/dns) endpoints. * Review setup and renewal history in [Domain Events](/user-guide/domains/events). # Quote domain registration Source: https://docs.bizzyco.ai/api-reference/domain-registrations/quote-domain-registration /api-reference/openapi.json get /v1/domain-registrations/quote Fetch a live domain registration quote # Register domain Source: https://docs.bizzyco.ai/api-reference/domain-registrations/register-domain /api-reference/openapi.json post /v1/domain-registrations Charge the account default payment method and enqueue domain registration provisioning. Requires an `Idempotency-Key` header so a retried request never charges twice. # Search domain registrations Source: https://docs.bizzyco.ai/api-reference/domain-registrations/search-domain-registrations /api-reference/openapi.json get /v1/domain-registrations/search Check availability for a domain registration query # Check domain email authentication Source: https://docs.bizzyco.ai/api-reference/domains/check-domain-email-authentication /api-reference/openapi.json post /v1/domains/{id}/email-authentication/check Perform one live DNS check for email-authentication records # Check domain verification Source: https://docs.bizzyco.ai/api-reference/domains/check-domain-verification /api-reference/openapi.json post /v1/domains/{id}/verification/check Perform one live DNS TXT lookup and update the domain verification status immediately. # Create DNS record Source: https://docs.bizzyco.ai/api-reference/domains/create-dns-record /api-reference/openapi.json post /v1/domains/{id}/dns-records Create one DNS record for a Bizzy-managed domain # Create verified domain attempt Source: https://docs.bizzyco.ai/api-reference/domains/create-verified-domain-attempt /api-reference/openapi.json post /v1/domains Create an externally owned domain verification attempt. The response includes the TXT instruction to publish. # Delete DNS record Source: https://docs.bizzyco.ai/api-reference/domains/delete-dns-record /api-reference/openapi.json delete /v1/domains/{id}/dns-records/{recordId} Delete one DNS record for a Bizzy-managed domain # Delete domain Source: https://docs.bizzyco.ai/api-reference/domains/delete-domain /api-reference/openapi.json delete /v1/domains/{id} Delete a domain from the authenticated organization. Verified domains can be deleted at any time; their DNS records at the external DNS host are left untouched. Registered Bizzy-managed domains can only be deleted once their registration has expired and their DNS zone holds no records beyond the zone's built-in ones (the apex NS set and SOA) — disable email for the domain first so Bizzy removes the email records it manages, and remove any remaining records yourself. A blocked deletion returns 409 with code REGISTERED_DOMAIN_NOT_EXPIRED, REGISTERED_DOMAIN_RENEWAL_IN_FLIGHT (a renewal is already queued or running for the domain), or REGISTERED_DOMAIN_DNS_NOT_EMPTY (which lists the blocking records in the error details). If the domain had email enabled, Bizzy also retires its email configuration — revoking the sending credential and removing the domain from the email provider. That cleanup is best-effort: if the provider is unreachable, the deletion still succeeds and any credential Bizzy could not revoke is recorded rather than lost track of. # Get DNS record Source: https://docs.bizzyco.ai/api-reference/domains/get-dns-record /api-reference/openapi.json get /v1/domains/{id}/dns-records/{recordId} Get one DNS record for a Bizzy-managed domain # Get domain Source: https://docs.bizzyco.ai/api-reference/domains/get-domain /api-reference/openapi.json get /v1/domains/{id} Get a domain by ID # Get domain email authentication Source: https://docs.bizzyco.ai/api-reference/domains/get-domain-email-authentication /api-reference/openapi.json get /v1/domains/{id}/email-authentication Get email-authentication readiness and DNS instructions # Get domain registration Source: https://docs.bizzyco.ai/api-reference/domains/get-domain-registration /api-reference/openapi.json get /v1/domains/{id}/registration Get registration settings for a Bizzy-managed domain # Get domain renewal price Source: https://docs.bizzyco.ai/api-reference/domains/get-domain-renewal-price /api-reference/openapi.json get /v1/domains/{id}/registration/renewal-price Live renewal price preview for a registered domain. Returns the exact amount the renewal workflow will enforce a `maxAmountCents` ceiling against — call this before POST /{id}/registration/renew. # Get domain verification Source: https://docs.bizzyco.ai/api-reference/domains/get-domain-verification /api-reference/openapi.json get /v1/domains/{id}/verification Get the current verification status and TXT instruction # Initiate domain verification Source: https://docs.bizzyco.ai/api-reference/domains/initiate-domain-verification /api-reference/openapi.json post /v1/domains/{id}/verification Start (or restart) TXT verification for a domain and begin background checking. A pending, unexpired verification is returned unchanged; a new token is issued only when there is no usable one (never started, failed, or expired). # List DNS records Source: https://docs.bizzyco.ai/api-reference/domains/list-dns-records /api-reference/openapi.json get /v1/domains/{id}/dns-records List DNS records for a Bizzy-managed domain # List domains Source: https://docs.bizzyco.ai/api-reference/domains/list-domains /api-reference/openapi.json get /v1/domains List domains for the authenticated organization # Renew domain Source: https://docs.bizzyco.ai/api-reference/domains/renew-domain /api-reference/openapi.json post /v1/domains/{id}/registration/renew Enqueue a domain renewal operation. The renewal workflow charges the account default payment method and refunds it if the registrar renewal fails. Requires an `Idempotency-Key` header so a retried request never enqueues a second renewal; a retry must reuse the original `periodYears` and `maxAmountCents` — a same-key request with different values is rejected. # Search domain availability Source: https://docs.bizzyco.ai/api-reference/domains/search-domain-availability /api-reference/openapi.json get /v1/domains/search Check availability and pricing for one or more domain names. Provide a fully-qualified `domain`, or a `query` label paired with one or more `tlds`. Prices are returned in integer cents (USD) with the standard markup applied. # Update DNS record Source: https://docs.bizzyco.ai/api-reference/domains/update-dns-record /api-reference/openapi.json put /v1/domains/{id}/dns-records/{recordId} Replace one DNS record for a Bizzy-managed domain # Update domain registrant contact Source: https://docs.bizzyco.ai/api-reference/domains/update-domain-registrant-contact /api-reference/openapi.json patch /v1/domains/{id}/registration/contact Update the stored registrant contact fields # Update domain registration settings Source: https://docs.bizzyco.ai/api-reference/domains/update-domain-registration-settings /api-reference/openapi.json patch /v1/domains/{id}/registration Update auto-renewal, WHOIS privacy, or transfer lock # Errors Source: https://docs.bizzyco.ai/api-reference/errors Understand Bizzy API error codes and responses The Bizzy API uses conventional HTTP status codes and returns detailed error information in JSON format to help you handle errors gracefully. ## Error Response Format All error responses follow a consistent structure: ```json theme={null} { "error": { "code": "ERROR_CODE", "message": "A human-readable description of the error", "details": { // Additional context (optional) } } } ``` | Field | Type | Description | | --------- | ------ | ------------------------------------------------------- | | `code` | string | A machine-readable error code for programmatic handling | | `message` | string | A human-readable description of what went wrong | | `details` | object | Additional context about the error (optional) | ## HTTP Status Codes | Status | Meaning | When It Occurs | | ------ | --------------------- | ------------------------------------------------------ | | `200` | OK | Request succeeded | | `201` | Created | Resource was created successfully | | `204` | No Content | Request succeeded with no response body (e.g., DELETE) | | `400` | Bad Request | Invalid request format or parameters | | `401` | Unauthorized | Missing or invalid API key | | `403` | Forbidden | Valid API key but insufficient permissions | | `404` | Not Found | Resource doesn't exist | | `429` | Too Many Requests | Rate limit exceeded | | `500` | Internal Server Error | Something went wrong on our end | | `503` | Service Unavailable | Temporary service outage | ## Error Codes Reference ### Authentication Errors | Code | Status | Description | | -------------------------- | ------ | ---------------------------------- | | `UNAUTHORIZED` | 401 | Invalid or missing API key | | `INSUFFICIENT_PERMISSIONS` | 403 | API key lacks required permissions | ```json theme={null} { "error": { "code": "UNAUTHORIZED", "message": "Invalid or missing API key" } } ``` ### Validation Errors | Code | Status | Description | | ------------------ | ------ | ----------------------------------- | | `VALIDATION_ERROR` | 400 | Request body failed validation | | `INVALID_INPUT` | 400 | Invalid query parameters or input | | `MISSING_QUERY` | 400 | Required query parameter is missing | Validation errors include details about which fields failed. `details` is a tree mirroring the request body: each node has an `errors` array (issues at that path), and object nodes additionally have a `properties` map keyed by field name. The top-level `errors` array carries issues that apply to the request as a whole. ```json theme={null} { "error": { "code": "VALIDATION_ERROR", "message": "Invalid request body", "details": { "errors": [], "properties": { "email": { "errors": ["Invalid email address"] }, "name": { "errors": [ "Too small: expected string to have >=1 characters" ] } } } } } ``` ### Resource Errors | Code | Status | Description | | --------------------- | ------ | -------------------------------- | | `NOT_FOUND` | 404 | Requested resource doesn't exist | | `INVALID_MESSAGE_ID` | 400 | Invalid message ID format | | `INVALID_CONTACT_ID` | 400 | Invalid contact ID format | | `INVALID_BUSINESS_ID` | 400 | Invalid business ID format | ```json theme={null} { "error": { "code": "NOT_FOUND", "message": "Contact not found" } } ``` For standard resources, `GET`, `PUT`/`PATCH`, and `DELETE` requests that target a resource which doesn't exist (or isn't visible to your organization) all return `404` with the `NOT_FOUND` code. Updating or deleting a missing resource is never a `500`. DNS record write operations (`PUT`/`DELETE /v1/domains/{id}/dns-records/{recordId}`) are the exception: they proxy Cloudflare, so a missing record surfaces the upstream status (typically `404`) with the `DNS_ERROR` code rather than `NOT_FOUND`. ### Domain Management Errors | Code | Status | Description | | --------------------------------- | ------ | ------------------------------------------------------- | | `REGISTRAR_UNSUPPORTED_OPERATION` | 422 | The requested operation isn't available for this domain | ```json theme={null} { "error": { "code": "REGISTRAR_UNSUPPORTED_OPERATION", "message": "WHOIS privacy is always enabled for this domain and cannot be disabled", "details": { "operation": "disabling WHOIS privacy" } } } ``` A small number of management operations aren't available for every domain — for example, some domains have WHOIS privacy permanently enabled, so it can't be disabled. When that happens the request returns `422` with this code and the affected `operation`. ### Rate Limiting Errors | Code | Status | Description | | -------------- | ------ | ----------------- | | `RATE_LIMITED` | 429 | Too many requests | ```json theme={null} { "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry after the number of seconds indicated by the Retry-After header." } } ``` A `429` from your plan's rate limit carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, and `Retry-After` headers — wait `Retry-After` seconds before retrying (fall back to exponential backoff if the header is absent). See [Rate Limits](/api-reference/rate-limits) for per-plan limits. ### Server Errors | Code | Status | Description | | --------------------- | ------ | ------------------------------- | | `INTERNAL_ERROR` | 500 | Unexpected server error | | `SERVICE_UNAVAILABLE` | 503 | Service temporarily unavailable | ```json theme={null} { "error": { "code": "INTERNAL_ERROR", "message": "An unexpected error occurred" } } ``` ## Handling Errors ### Basic Error Handling ```typescript TypeScript theme={null} async function makeRequest() { const response = await fetch('https://api.bizzyco.ai/v1/contacts', { headers: { 'Authorization': `Bearer ${apiKey}`, }, }); if (!response.ok) { const { error } = await response.json(); switch (response.status) { case 401: throw new Error('Invalid API key'); case 403: throw new Error(`Permission denied: ${error.message}`); case 404: throw new Error('Resource not found'); case 429: throw new Error('Rate limited - retry later'); default: throw new Error(error.message || 'Request failed'); } } return response.json(); } ``` ```python Python theme={null} import requests def make_request(): response = requests.get( 'https://api.bizzyco.ai/v1/contacts', headers={'Authorization': f'Bearer {api_key}'} ) if not response.ok: error = response.json().get('error', {}) if response.status_code == 401: raise Exception('Invalid API key') elif response.status_code == 403: raise Exception(f"Permission denied: {error.get('message')}") elif response.status_code == 404: raise Exception('Resource not found') elif response.status_code == 429: raise Exception('Rate limited - retry later') else: raise Exception(error.get('message', 'Request failed')) return response.json() ``` ### Retry with Exponential Backoff For transient errors (429, 500, 503), implement retry logic with exponential backoff: ```typescript TypeScript theme={null} async function fetchWithRetry( url: string, options: RequestInit, maxRetries = 3 ): Promise { let lastError: Error; for (let attempt = 0; attempt < maxRetries; attempt++) { try { const response = await fetch(url, options); // Don't retry client errors (except rate limiting) if (response.ok || (response.status >= 400 && response.status < 500 && response.status !== 429)) { return response; } // For rate limiting, use Retry-After header if available if (response.status === 429) { const retryAfter = response.headers.get('Retry-After'); const delay = retryAfter ? parseInt(retryAfter) * 1000 : Math.pow(2, attempt) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); continue; } // For server errors, use exponential backoff if (response.status >= 500) { const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s await new Promise(resolve => setTimeout(resolve, delay)); continue; } return response; } catch (error) { lastError = error as Error; const delay = Math.pow(2, attempt) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); } } throw lastError!; } ``` ```python Python theme={null} import time import requests def fetch_with_retry(url, headers, max_retries=3): last_error = None for attempt in range(max_retries): try: response = requests.get(url, headers=headers) # Don't retry client errors (except rate limiting) if response.ok or (400 <= response.status_code < 500 and response.status_code != 429): return response # For rate limiting, use Retry-After header if available if response.status_code == 429: retry_after = response.headers.get('Retry-After') delay = int(retry_after) if retry_after else (2 ** attempt) time.sleep(delay) continue # For server errors, use exponential backoff if response.status_code >= 500: delay = 2 ** attempt # 1s, 2s, 4s time.sleep(delay) continue return response except requests.RequestException as e: last_error = e delay = 2 ** attempt time.sleep(delay) raise last_error ``` ## Best Practices Use the `code` field for programmatic error handling, not the `message`. Error messages may change, but error codes remain stable. Include the request ID from response headers (`X-Request-ID`) when logging errors to help with debugging and support requests. Walk the `details` tree (each node's `errors` array, recursing into `properties`) to show specific field errors to your users rather than generic error messages. # Create access link Source: https://docs.bizzyco.ai/api-reference/file-access-links/create-access-link /api-reference/openapi.json post /v1/files/{id}/access-links Create a new access link for a file # List access links Source: https://docs.bizzyco.ai/api-reference/file-access-links/list-access-links /api-reference/openapi.json get /v1/files/{id}/access-links List all access links for a specific file with pagination # Delete file Source: https://docs.bizzyco.ai/api-reference/files/delete-file /api-reference/openapi.json delete /v1/files/{id} Delete a file from storage and database # Download file Source: https://docs.bizzyco.ai/api-reference/files/download-file /api-reference/openapi.json get /v1/files/{id}/download Download the file content # Download file via access link Source: https://docs.bizzyco.ai/api-reference/files/download-file-via-access-link /api-reference/openapi.json get /v1/files/public/{token} Download a file using a public access link token. No authentication required. # Get file Source: https://docs.bizzyco.ai/api-reference/files/get-file /api-reference/openapi.json get /v1/files/{id} Get a specific file by ID with full details # List files Source: https://docs.bizzyco.ai/api-reference/files/list-files /api-reference/openapi.json get /v1/files List all files with full details and pagination support # Search files Source: https://docs.bizzyco.ai/api-reference/files/search-files /api-reference/openapi.json get /v1/files/search Full-text search files by name, description, or content # Update file Source: https://docs.bizzyco.ai/api-reference/files/update-file /api-reference/openapi.json put /v1/files/{id} Update an existing file metadata # Upload file Source: https://docs.bizzyco.ai/api-reference/files/upload-file /api-reference/openapi.json post /v1/files/upload Upload a new file. Uses multipart form data with the file and optional metadata. # Create folder Source: https://docs.bizzyco.ai/api-reference/folders/create-folder /api-reference/openapi.json post /v1/folders Create a new folder # Delete folder Source: https://docs.bizzyco.ai/api-reference/folders/delete-folder /api-reference/openapi.json delete /v1/folders/{id} Delete a folder. Subfolders will be cascade deleted. Files in the folder will have their folderId set to null. # Get folder Source: https://docs.bizzyco.ai/api-reference/folders/get-folder /api-reference/openapi.json get /v1/folders/{id} Get a specific folder by ID with full details (including file/subfolder counts) # List folders Source: https://docs.bizzyco.ai/api-reference/folders/list-folders /api-reference/openapi.json get /v1/folders List all folders with full details (including file/subfolder counts) and pagination support # Update folder Source: https://docs.bizzyco.ai/api-reference/folders/update-folder /api-reference/openapi.json put /v1/folders/{id} Update an existing folder # Introduction Source: https://docs.bizzyco.ai/api-reference/introduction Learn the basics of the Bizzy API The Bizzy API provides programmatic access to your business communication data, including messages, contacts, customers, and businesses. Use it to build integrations, automate workflows, and extend Bizzy's capabilities. **Quick reference for AI agents:** ```json theme={null} { "baseUrl": "https://api.bizzyco.ai/v1", "auth": "Authorization: Bearer ", "responseEnvelope": { "data": "T", "meta": { "pagination": { "limit": 10, "offset": 0, "hasMore": true } } }, "errorEnvelope": { "error": { "message": "string", "code": "string", "details": "object|undefined" } }, "pagination": ["limit (1-100)", "offset (>=0)", "sortOrder (asc|desc)"], "ids": "UUIDv4", "timestamps": "ISO 8601 UTC" } ``` ## Base URL All API requests should be made to: ``` https://api.bizzyco.ai/v1 ``` Do not include a trailing slash in the base URL. Endpoints are appended directly, e.g., `https://api.bizzyco.ai/v1/contacts`. The API is versioned, with `v1` being the current stable version. When breaking changes are introduced, a new version will be released. ## Request Format The API accepts JSON-encoded request bodies and returns JSON-encoded responses. ```bash cURL theme={null} curl -X POST https://api.bizzyco.ai/v1/messages \ -H "Authorization: Bearer sk_live_abc123..." \ -H "Content-Type: application/json" \ -d '{"to": "user@example.com", "subject": "Hello"}' ``` ```typescript TypeScript theme={null} const response = await fetch('https://api.bizzyco.ai/v1/messages', { method: 'POST', headers: { Authorization: 'Bearer sk_live_abc123...', 'Content-Type': 'application/json', }, body: JSON.stringify({ to: 'user@example.com', subject: 'Hello', }), }); const data = await response.json(); ``` ```python Python theme={null} import requests response = requests.post( 'https://api.bizzyco.ai/v1/messages', headers={ 'Authorization': 'Bearer sk_live_abc123...', 'Content-Type': 'application/json', }, json={ 'to': 'user@example.com', 'subject': 'Hello', } ) data = response.json() ``` ### Required Headers | Header | Value | Description | | --------------- | ------------------ | ------------------------------------------ | | `Authorization` | `Bearer ` | Your API key for authentication | | `Content-Type` | `application/json` | Required for POST, PUT, and PATCH requests | ### Response Headers Every authenticated API response includes these headers: | Header | Description | | ----------------------- | ------------------------------------------------------------------------------------- | | `X-Request-ID` | Unique identifier for the request. Include this when contacting support for debugging | | `X-RateLimit-Limit` | Your plan's per-minute request limit | | `X-RateLimit-Remaining` | Requests remaining in the current window | | `X-RateLimit-Reset` | Seconds until your allowance is fully replenished | See [Rate Limits](/api-reference/rate-limits) for per-plan limits and how to handle `429` responses. ## Shared conventions Every endpoint in the API follows the same conventions for response shape, pagination, errors, timestamps, and IDs. Once you've learned them here, you can skim the resource-specific reference pages without rediscovering them each time. ### Response envelope All successful responses wrap the payload in a `data` field: ```json theme={null} { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "subject": "Hello", "status": "sent", "createdAt": "2024-01-15T09:30:00Z", "updatedAt": "2024-01-15T09:30:00Z" } } ``` List endpoints add a `meta.pagination` block: ```json theme={null} { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "subject": "Hello", "status": "sent" }, { "id": "550e8400-e29b-41d4-a716-446655440001", "subject": "Follow-up", "status": "draft" } ], "meta": { "pagination": { "limit": 10, "offset": 0, "total": 42, "hasMore": true } } } ``` `hasMore` is computed server-side. `total` is included when the underlying query can provide it cheaply; otherwise it is omitted and you should rely on `hasMore` to know when to stop paginating. The request identifier is returned in the `X-Request-ID` response header, not in the body. When `total` is omitted, `hasMore` is inferred from whether the page returned exactly `limit` items. This means a page that happens to fill exactly to `limit` will report `hasMore: true` even if it is the last page — your next request will simply return an empty `data` array. Always stop paginating when you receive an empty page, not just when `hasMore` becomes `false`. ### Pagination List endpoints accept three query parameters: | Parameter | Default | Accepted values | Description | | ----------- | ------- | --------------- | ---------------------------------------- | | `limit` | 10 | 1–100 | Number of items to return | | `offset` | 0 | ≥ 0 | Number of items to skip | | `sortOrder` | `desc` | `asc` \| `desc` | Sort direction, typically by `createdAt` | The API is offset-based; cursor-based pagination is not available today. ```bash theme={null} curl "https://api.bizzyco.ai/v1/contacts?limit=20&offset=40&sortOrder=asc" \ -H "Authorization: Bearer sk_live_abc123..." ``` ### Error responses Errors use a single consistent shape: ```json theme={null} { "error": { "message": "Validation failed", "code": "VALIDATION_ERROR", "details": { "errors": [], "properties": { "email": { "errors": ["Invalid email address"] } } } } } ``` `details` is present on validation errors and omitted otherwise. Validation errors are returned as a tree mirroring the request body: each node has an `errors` array (issues that apply at that path), and object nodes additionally have a `properties` map keyed by field name. The top-level `errors` array carries issues that apply to the request as a whole. Status codes you'll see: | Status | Meaning | | ------ | -------------------------------------------------------- | | `400` | Validation error or malformed request | | `401` | Missing or invalid API key | | `403` | API key lacks the permissions required for this endpoint | | `404` | Resource does not exist (or is soft-deleted) | | `429` | Rate limit exceeded — see the `Retry-After` header | | `500` | Unexpected server error | | `503` | Temporarily unavailable (e.g., database outage) | See [Error Handling](/api-reference/errors) for the full list of error codes. ### Soft deletes `DELETE` endpoints perform soft deletes: the record is retained with a `deletedAt` timestamp set. Soft-deleted records are filtered out of list and get responses — there is currently no query flag to include them. If you need to recover a record, contact support. ### Timestamps and IDs * **Timestamps** are ISO 8601 UTC strings, e.g., `2024-01-15T09:30:00Z`. Every resource returns `createdAt` and `updatedAt`, plus a nullable `deletedAt`. * **Identifiers** are UUID v4 strings (for example, `550e8400-e29b-41d4-a716-446655440000`). Every resource uses `id` as its primary key, and foreign keys follow the `Id` convention (`contactId`, `businessId`, etc.). ## SDKs Official SDKs for TypeScript and Python are coming soon. In the meantime, you can use the REST API directly with any HTTP client. ## OpenAPI Specification The Bizzy API is documented using OpenAPI 3.1. You can access the specification at: ``` https://api.bizzyco.ai/v1/openapi.json ``` Use this to generate client libraries, import into API tools like Postman, or explore the API programmatically. ## Next Steps Learn how to create and use API keys Understand error responses and codes # Get message attachment Source: https://docs.bizzyco.ai/api-reference/message-attachments/get-message-attachment /api-reference/openapi.json get /v1/messages/{id}/attachments/{attachmentId} Get a specific attachment for a message # List message attachments Source: https://docs.bizzyco.ai/api-reference/message-attachments/list-message-attachments /api-reference/openapi.json get /v1/messages/{id}/attachments List all attachments for a specific message # Get message contact Source: https://docs.bizzyco.ai/api-reference/message-contacts/get-message-contact /api-reference/openapi.json get /v1/messages/{id}/contacts/{contactId} Get a specific contact association for a message # List message contacts Source: https://docs.bizzyco.ai/api-reference/message-contacts/list-message-contacts /api-reference/openapi.json get /v1/messages/{id}/contacts List all contacts associated with a specific message # Delete message Source: https://docs.bizzyco.ai/api-reference/messages/delete-message /api-reference/openapi.json delete /v1/messages/{id} Delete a message (soft delete) # Get archived messages count Source: https://docs.bizzyco.ai/api-reference/messages/get-archived-messages-count /api-reference/openapi.json get /v1/messages/archived/count Get the count of archived messages # Get message Source: https://docs.bizzyco.ai/api-reference/messages/get-message /api-reference/openapi.json get /v1/messages/{id} Get a specific message by ID # Get messages by contact Source: https://docs.bizzyco.ai/api-reference/messages/get-messages-by-contact /api-reference/openapi.json get /v1/messages/contacts/{contactId}/messages Get all messages associated with a specific contact # Get messages by email address Source: https://docs.bizzyco.ai/api-reference/messages/get-messages-by-email-address /api-reference/openapi.json get /v1/messages/email-address/{emailAddressId}/messages Get all messages associated with a specific email address # Get messages by thread Source: https://docs.bizzyco.ai/api-reference/messages/get-messages-by-thread /api-reference/openapi.json get /v1/messages/thread/{threadId} Get all messages in a specific thread # Get snoozed messages count Source: https://docs.bizzyco.ai/api-reference/messages/get-snoozed-messages-count /api-reference/openapi.json get /v1/messages/snoozed/count Get the count of snoozed messages # List archived messages Source: https://docs.bizzyco.ai/api-reference/messages/list-archived-messages /api-reference/openapi.json get /v1/messages/archived List all archived messages with pagination support # List incoming messages Source: https://docs.bizzyco.ai/api-reference/messages/list-incoming-messages /api-reference/openapi.json get /v1/messages/incoming List all incoming messages with pagination support # List messages Source: https://docs.bizzyco.ai/api-reference/messages/list-messages /api-reference/openapi.json get /v1/messages List all messages with pagination support # List outgoing messages Source: https://docs.bizzyco.ai/api-reference/messages/list-outgoing-messages /api-reference/openapi.json get /v1/messages/outgoing List all outgoing messages with pagination support # List snoozed messages Source: https://docs.bizzyco.ai/api-reference/messages/list-snoozed-messages /api-reference/openapi.json get /v1/messages/snoozed List all snoozed messages with pagination support # Update message Source: https://docs.bizzyco.ai/api-reference/messages/update-message /api-reference/openapi.json patch /v1/messages/{id} Update a message read status. Only readAt, archivedAt, and snoozedUntil fields are allowed. # Get operation Source: https://docs.bizzyco.ai/api-reference/operations/get-operation /api-reference/openapi.json get /v1/operations/{operationId} Get a domain registration or renewal operation by ID # Rate Limits Source: https://docs.bizzyco.ai/api-reference/rate-limits Understand API rate limits and how to handle them The Bizzy API enforces per-minute rate limits to ensure fair usage and maintain service stability for all users. ## Limits by Plan Rate limits are applied per account and scale with your plan: | Plan | API requests per minute | | ------------ | ----------------------- | | Free | 10 | | Starter | 60 | | Professional | 300 | | Enterprise | 1,000 | The limit is also the burst capacity: you can spend your full per-minute allowance at once, and it replenishes continuously over the following minute. See [Understanding Limits](/admin-guide/billing/limits) for how rate limits fit into your plan. ## Rate Limit Headers Every authenticated API response includes headers describing your current allowance: | Header | Description | | ----------------------- | ----------------------------------------------------------------- | | `X-RateLimit-Limit` | Your plan's per-minute request limit (burst capacity) | | `X-RateLimit-Remaining` | Requests remaining right now | | `X-RateLimit-Reset` | Seconds until your allowance is fully replenished | | `Retry-After` | On `429` responses only — seconds to wait before the next request | ## Handling Rate Limits When you exceed your rate limit, the API returns a `429 Too Many Requests` response: ```json theme={null} { "error": { "code": "RATE_LIMITED", "message": "Rate limit exceeded. Retry after the number of seconds indicated by the Retry-After header." } } ``` Wait the number of seconds given by the `Retry-After` header, then retry. ### Implementing Rate Limit Handling ```typescript TypeScript theme={null} async function fetchWithRateLimit( url: string, options: RequestInit, attempt = 0, ): Promise { const response = await fetch(url, options); if (response.status === 429) { const retryAfter = response.headers.get('Retry-After'); const retryAfterS = retryAfter === null ? Number.NaN : Number(retryAfter); // Fall back to exponential backoff if the header is ever missing. const waitMs = Number.isFinite(retryAfterS) ? retryAfterS * 1_000 : Math.min(60_000, 1_000 * 2 ** attempt); console.log(`Rate limited. Waiting ${waitMs}ms before retry...`); await new Promise(resolve => setTimeout(resolve, waitMs)); return fetchWithRateLimit(url, options, attempt + 1); } return response; } ``` ```python Python theme={null} import time import requests def fetch_with_rate_limit(url, headers, attempt=0): response = requests.get(url, headers=headers) if response.status_code == 429: retry_after_s = int(response.headers.get('Retry-After', 2 ** attempt)) print(f'Rate limited. Waiting {retry_after_s}s before retry...') time.sleep(retry_after_s) return fetch_with_rate_limit(url, headers, attempt + 1) return response ``` ## Best Practices Instead of making requests as fast as possible, implement a queue that spreads requests evenly across your rate limit window. ```typescript theme={null} class RequestQueue { private queue: Array<() => Promise> = []; private processing = false; private requestsPerSecond: number; constructor(requestsPerMinute: number) { this.requestsPerSecond = requestsPerMinute / 60; } async add(fn: () => Promise): Promise { return new Promise((resolve, reject) => { this.queue.push(async () => { try { resolve(await fn()); } catch (e) { reject(e); } }); this.process(); }); } private async process() { if (this.processing) return; this.processing = true; while (this.queue.length > 0) { const fn = this.queue.shift()!; await fn(); await new Promise(r => setTimeout(r, 1000 / this.requestsPerSecond) ); } this.processing = false; } } ``` When you receive a 429 response, wait the number of seconds given by the `Retry-After` header before retrying. If you retry sooner, the request will simply be denied again. Slow down proactively as `X-RateLimit-Remaining` approaches zero instead of running into 429s — for example, pause your queue until `X-RateLimit-Reset` seconds have passed. Reduce API calls by caching responses that don't change frequently. This is especially useful for reference data like contact lists or business details. Where available, use batch endpoints to perform multiple operations in a single request instead of making separate calls. ## Increasing Your Limits Rate limits scale with your plan — upgrading raises your per-minute limit. If your integration genuinely needs a higher request rate than the Enterprise plan provides, contact [support@bizzyco.ai](mailto:support@bizzyco.ai) to discuss your use case. ## Next Steps View pricing and upgrade options Understand error responses and codes # List task activity Source: https://docs.bizzyco.ai/api-reference/task-activity/list-task-activity /api-reference/openapi.json get /v1/tasks/{id}/activity Get the activity history for a specific task showing all changes, assignments, and status updates # Assign user to task Source: https://docs.bizzyco.ai/api-reference/task-assignees/assign-user-to-task /api-reference/openapi.json post /v1/tasks/{id}/assignees Assign a user to a task # List task assignees Source: https://docs.bizzyco.ai/api-reference/task-assignees/list-task-assignees /api-reference/openapi.json get /v1/tasks/{id}/assignees List all users assigned to a specific task # Unassign user from task Source: https://docs.bizzyco.ai/api-reference/task-assignees/unassign-user-from-task /api-reference/openapi.json delete /v1/tasks/{id}/assignees/{userId} Remove a user assignment from a task # Create task Source: https://docs.bizzyco.ai/api-reference/tasks/create-task /api-reference/openapi.json post /v1/tasks Create a new task # Delete task Source: https://docs.bizzyco.ai/api-reference/tasks/delete-task /api-reference/openapi.json delete /v1/tasks/{id} Delete a task (soft delete) # Get task Source: https://docs.bizzyco.ai/api-reference/tasks/get-task /api-reference/openapi.json get /v1/tasks/{id} Get a specific task by ID with full details and assignees # List tasks Source: https://docs.bizzyco.ai/api-reference/tasks/list-tasks /api-reference/openapi.json get /v1/tasks List all tasks with full details, assignees, and pagination support. Supports filtering by status, category, urgency, importance, assignee, and due date. # Partially update task Source: https://docs.bizzyco.ai/api-reference/tasks/partially-update-task /api-reference/openapi.json patch /v1/tasks/{id} Partially update an existing task. Only provided fields will be updated. # Search tasks Source: https://docs.bizzyco.ai/api-reference/tasks/search-tasks /api-reference/openapi.json get /v1/tasks/search Search tasks using full-text search across title, description, and metadata # Update task Source: https://docs.bizzyco.ai/api-reference/tasks/update-task /api-reference/openapi.json put /v1/tasks/{id} Update an existing task. Note: This endpoint accepts partial updates (same behavior as PATCH). # Agents Source: https://docs.bizzyco.ai/get-started/concepts/agents What agents are, how they differ from automations, and how you control them Bizzy has two kinds of AI worker: **agents** and **automations**. They look similar from a distance — both use LLMs, both can call tools, both can read your data and act on it — but they answer different questions, and using them interchangeably is the most common source of confusion for new users. Read this page, then read [Automations](/get-started/concepts/automations). Together they give you a clear sense of which one to reach for. ## Agents vs. Automations at a Glance | | **Agent** | **Automation** | | ------------------ | ------------------------------------------------------------- | ----------------------------------------------------------- | | **Triggered by** | A person chatting with it (or another workflow invoking it) | A platform event — new message, new contact, schedule, etc. | | **Shape** | A conversational LLM loop that calls tools to get things done | A rule that says "when X happens, do Y" | | **Has memory of?** | Yes — every turn of the conversation | No — each execution is fresh | | **Best for** | Open-ended help, research, multi-turn judgement | Routine, event-driven work that should just happen | A useful intuition: an **automation** is a tireless junior employee waiting for the inbox to ping. An **agent** is a colleague you can ask things of. The two cooperate. An automation can invoke an agent as one of its steps when the work needs more nuance than rules can capture — for example, "when a new email arrives, ask the support agent to draft a reply." ## What is an Agent? An agent is a configured persona that runs an LLM loop. When you create an agent you decide: * **Name and system prompt** — who the agent is and how it should behave. * **Model** — which LLM powers it. * **Tools it has access to** — and at what permission level. * **Step budget** — `maxSteps` caps how many tool calls a single response can make. The default is **5**. * **LLM parameters** — temperature, top-p, frequency/presence penalties, and so on, for power users. When a person (or another workflow) sends the agent a message, it runs an agentic loop: read the message, choose a tool to call, get the result, choose another tool, until it's done or it hits its step budget. The conversation state is kept warm for the duration, so follow-up messages pick up right where the last one left off. ## Tool Permissions Tools are the only way an agent affects the world — read your contacts, send an email, create a task, search files. Bizzy gives you granular control over each tool, with three levels: | Level | Behaviour | | ----------- | --------------------------------------------------------------------------------------------------- | | **`allow`** | Agent calls the tool automatically, no prompt | | **`ask`** | Agent must request approval before each call; you see what it wants to do and can approve or reject | | **`deny`** | Tool is hidden from the agent entirely | Sensible defaults are applied for you: **read-style tools default to `allow`** (an agent should be able to look things up without asking permission), **write- and delete-style tools default to `ask`** (anything that mutates state should pause for a human). You can override any of these per agent. ## Conversations Every chat with an agent is recorded as an **agent conversation** — a thread you can revisit, share, or audit later. Each conversation has: * A **status**: `active`, `completed`, `timeout`, or `error`. * A **source**: `web` (the dashboard chat UI), `api`, or `mcp` (a Model Context Protocol client like Claude Desktop or Cursor). * The full transcript, including tool calls, tool results, and any approval decisions. Conversations are how you scale review of AI work without watching every step in real time. You can browse the conversation history of any agent and see exactly what it did and why. ## How an Agent Runs ```mermaid theme={null} graph TD A[User sends message] --> B[Conversation resumes] B --> C{LLM decides:
tool call or reply?} C -->|tool| D[Permission check] D -->|allow| E[Run tool] D -->|ask| F[Pause for approval] F --> E E --> C C -->|reply| G[Stream reply to user] G --> H[Conversation persisted] ``` The loop is bounded — `maxSteps` is a hard cap on tool calls per turn — and is interruptible. If a permission prompt comes back denied, or if you pause the conversation, the agent stops cleanly. ## When to Use Which Reach for an **agent** when: * You want to ask follow-up questions in a conversation. * The work needs judgement, not just rules — "summarise this account's recent activity," "draft a polite refund refusal." * You want a human in the loop on writes. Reach for an **automation** when: * The trigger is an event you can describe — "a new email arrives," "a customer signs up." * You want it to run forever, untouched, until you tell it to stop. * The behaviour is predictable enough that you don't need to chat about it. When in doubt: if you'd ever consider hitting "send" yourself before the action happens, you probably want an agent. If the action should *always* happen the moment the trigger fires, you probably want an automation. ## Related Topics The other half of this story Build your first agent in the web app Configure allow / ask / deny for each tool Browse and audit past chats # Automations Source: https://docs.bizzyco.ai/get-started/concepts/automations How AI-powered automations work in Bizzy Automations are how Bizzy turns your inbox from a task list into a system that works for you. Instead of manually processing every message, you define rules in plain English and let AI handle the routine work. ## What Are Automations? An **automation** is a workflow that runs when something happens in Bizzy. Every automation has three parts: 1. **Trigger** — the event that starts the automation (e.g., a new email arrives) 2. **Instructions** — what you want the AI to do, written in natural language 3. **Permissions** — what actions the automation is allowed to take What makes Bizzy automations different from traditional "if this, then that" rules is the **AI layer**. Instead of rigid conditions and fixed responses, you describe what you want in plain English and the AI interprets each situation individually. ## Automations vs. Agents Bizzy has two kinds of AI worker, and they're easy to confuse. **Automations** are event-triggered: a message arrives, a contact is created, a schedule fires, and the automation runs without anyone being there. **Agents** are conversational: you (or another workflow) chat with them, and they call tools to get things done across multiple turns. A useful intuition: an automation is a junior employee waiting for the inbox to ping. An agent is a colleague you can ask things of. Automations *can* invoke an agent as one of their steps when the work needs more nuance than rules can capture — for example, "when a new email arrives, ask the support agent to draft a reply." If you'd ever want to hit "send" yourself before the action happens, reach for an [agent](/get-started/concepts/agents). If the action should *always* happen the moment the trigger fires, reach for an automation. ## How Automations Work When an event occurs — say a new email arrives — Bizzy checks if any active automations match that trigger. If so, the AI reads the incoming content, evaluates your instructions, and takes action. Here's the flow: 1. **Event occurs** — A new email, contact creation, or other trigger event happens 2. **Trigger matches** — Bizzy identifies every automation listening for this event; all matching enabled automations run independently 3. **AI processes** — The AI reads the content and interprets your instructions 4. **Action taken** — The AI performs the appropriate action (reply, create contact, etc.) 5. **Result logged** — The execution is recorded so you can review what happened The AI doesn't follow a decision tree — it understands context. An instruction like "if this looks like a support request, send an acknowledgment" works because the AI can evaluate whether an email is a support request, even if the sender doesn't use the word "support." ## The Power of Natural Language Instructions Traditional automation tools require you to define exact conditions: "if subject contains 'help' OR subject contains 'support' OR subject contains 'issue'..." This is brittle and misses edge cases. Bizzy automations use AI instructions instead: ``` When a new email arrives: 1. If it looks like a support request, send a friendly acknowledgment 2. If it's a sales inquiry, tag the contact as "Lead" 3. If it's a newsletter or automated notification, do nothing ``` The AI handles the ambiguity. It understands that "My login isn't working" is a support request even though it doesn't contain the word "support." ## What Can Automations Do? Automations can take a range of actions depending on their permissions: * **Send replies** — Compose and send email responses * **Create and update contacts** — Add new contacts or update existing ones * **Manage messages** — Archive, label, or categorize incoming messages * **Send notifications** — Alert team members about important messages * **Create tasks** — Generate follow-up tasks from incoming requests ## Automation Lifecycle Automations have a lifecycle with different states: | Status | Meaning | | ------------- | ------------------------------------------------- | | **Active** | Running and processing events as they occur | | **Paused** | Temporarily disabled — can be resumed at any time | | **Completed** | Finished after reaching an execution limit | | **Expired** | Past its configured expiration date | You can pause an automation at any time without losing its configuration. This is useful when you want to temporarily stop processing while you refine your instructions. ## Automations and Permissions Automations run with the permissions that were set when they were created. They cannot perform actions beyond their granted permissions. This means: * An automation with read-only message access can analyze emails but not reply * An automation without contact permissions cannot create or modify contacts * Permissions are checked on every execution, not just at creation time This design ensures automations stay within the boundaries you define, even as the AI interprets instructions flexibly. ## Related Topics Step-by-step guide to building an automation Build a working AI-powered support workflow from scratch The conversational counterpart — when to reach for one instead # Businesses Source: https://docs.bizzyco.ai/get-started/concepts/businesses How Bizzy models the businesses you run inside one organization In Bizzy, your **organization** is your account — the container for users, billing, and data. Inside that account, you run one or more **businesses**. The distinction matters: most plans support multiple businesses per organization, and each business has its own profile, products, locations, and Stripe connection. If you operate a single business, the difference is mostly invisible — your one business sits inside your one organization, and you rarely think about it. If you operate several (an agency with multiple service lines, a holding company with separate brands, or a contractor who runs both a roofing and a solar business under one team), the multi-business model is the spine of how Bizzy organizes everything else. ## What a Business Is A business represents a real-world commercial entity. It has: * A **profile** — name, industries, description, and a flexible field for whatever else you need to record. * A set of **offerings** — the products and services it sells. * **Online presences** — websites, social accounts, marketplace listings. * **Physical presences** — locations, addresses, service areas. * An optional **Stripe connection** — its own connected Stripe account for payments. A business is the customer-facing identity Bizzy grounds itself in: when an agent drafts a reply or an automation composes an email on your behalf, the business profile, offerings, and presences tell the AI *which* business it's speaking for. Records like contacts, customers, and messages live at the organization level today; business-level scoping for agents and automations is on the roadmap. ## Business vs. Organization The two concepts are easy to conflate. The short version: | | **Organization** | **Business** | | --------------------- | ---------------------------- | ------------------------------------------------ | | **What it is** | Your Bizzy account | A commercial entity you run inside the account | | **Holds** | Users, billing, settings | Profile, offerings, presences, Stripe | | **How many you have** | One per account | One or more | | **Used for** | Access control, subscription | Customer-facing identity, payments, AI grounding | The organization is the *container*. The business is the *thing the world sees*. ## Profile The business profile is what your AI grounds itself in when it speaks on your behalf. It includes: * **Name** — the public-facing name. * **Industries** — one or more industries (e.g. roofing, HVAC, professional services). * **Description** — a free-form pitch the AI can lean on when drafting messages. * **Custom data** — a flexible field for anything else you want recorded. When an agent writes an email or an automation drafts a reply, it reads the business profile to stay on-brand and on-topic. ## Offerings An **offering** is something the business sells. It's tagged as either a **product** (something tangible or fixed) or a **service** (something delivered). Each offering has a name and description; together they define what the business actually does. Offerings power AI features that need to know your catalogue — for example, when an inbound message asks "do you do gutter cleaning?" the agent needs to know whether the answer is yes. ## Presences Presences answer the question "where is this business in the world?" — both digitally and physically. **Online presences** capture the digital footprint: a primary website, social media profiles, marketplace listings, review pages. Each entry has a type, provider, URL, and description. **Physical presences** capture the bricks-and-mortar side: an office, a warehouse, a service area. Each entry has a name, description, and address. Together they let agents and automations answer location-aware questions — "what's your address?", "do you serve this zip code?", "what's your Yelp page?" — with truthful, current data. ## Stripe Connect Each business can connect **its own** Stripe account through Stripe Connect. The connection lives at the business level, not the organization level — meaning two businesses inside the same organization can independently link to two different Stripe accounts, with separate customers, invoices, and sync schedules. Once connected, Bizzy keeps the business's customers and transactions in sync with its Stripe account. The connection has three sync modes: * **`off`** — Stripe is not connected, or sync is disabled. * **`one_way`** — data flows from Stripe into Bizzy only (a read-only mirror). * **`two_way`** — data flows in both directions. You can switch modes and trigger manual syncs from the business settings page. ## Putting It Together ```mermaid theme={null} graph TD O[Organization] --> B1[Business: Acme Roofing] O --> B2[Business: Acme Solar] B1 --> P1[Profile] B1 --> O1[Offerings] B1 --> N1[Online Presences] B1 --> H1[Physical Presences] B1 --> S1[Stripe Account] B2 --> P2[Profile] B2 --> O2[Offerings] B2 --> N2[Online Presences] B2 --> H2[Physical Presences] B2 --> S2[Stripe Account] ``` One organization. Two businesses. Two Stripe accounts. Two distinct profiles, catalogues, and footprints. One team running both. ## Related Topics Edit name, industries, and description Manage your product and service catalogue Online and physical locations Link a Stripe account to a business # Contacts, Customers & Businesses Source: https://docs.bizzyco.ai/get-started/concepts/contacts Understand how Bizzy organizes people and business relationships Bizzy provides three ways to organize the people and companies you work with: **Contacts**, **Customers**, and **Businesses**. Each serves a different purpose, and understanding the distinction helps you get the most from the platform. ## Overview | Type | What It Represents | Example | | ------------ | ----------------------------------------- | ------------------------------------------------------- | | **Contact** | An individual person you communicate with | John Smith, [jane@example.com](mailto:jane@example.com) | | **Customer** | A business relationship with a person | John Smith as a buyer | | **Business** | A company or organization | Acme Corporation | ## Contacts A **contact** represents an individual person. Contacts are the core of Bizzy's data model — they're the link between people and the messages you exchange with them. Every contact can have multiple email addresses and phone numbers, each with labels like "work" or "personal." When Bizzy receives a message, it matches the sender's email to an existing contact, linking the message to that person's history automatically. This means you can open any contact and see every conversation you've had with them, across all channels. Contacts are also created automatically when you receive emails from new senders, so your address book grows organically as you communicate. ## Customers A **customer** represents a business relationship. While a contact is just a person in your address book, a customer indicates they have a commercial relationship with you — they've bought something, signed up for a service, or are in your sales pipeline. Customers can have **transactions** associated with them — records of purchases, payments, or other financial events. This gives you a financial history tied to a person, separate from your communication history. ### When to Use Customers * Someone makes a purchase or payment * You want to track an ongoing client relationship * You need to record transaction history * You're building a sales pipeline ## Businesses A **business** represents a company or organization. Where contacts track individuals and customers track financial relationships, businesses track company-level information: industry, offerings, online presence, and physical locations. Businesses can be connected to contacts (people who work there) and customers (commercial relationships), giving you both the company-level and individual views. ## How They Work Together These three types form a hierarchy that mirrors real business relationships: ``` Business: Acme Corporation ├── Contact: John Smith (Sales Manager) │ └── Customer: John Smith (purchased in 2024) ├── Contact: Jane Doe (CEO) └── Contact: Bob Wilson (Support) ``` In this example: * **Acme Corporation** is tracked as a business with its company information * **John**, **Jane**, and **Bob** are contacts (individuals) * **John** is also a customer because he's made purchases ## Choosing the Right Type The general rule: * **Start with contacts.** Every person you communicate with should be a contact. Bizzy creates these automatically from email senders. * **Add customer records for buyers.** When someone makes a purchase or becomes a client, create a customer record to track the financial relationship. * **Add businesses for companies.** When you need to track company-level information — their products, locations, or team — create a business and link relevant contacts to it. ## Related Topics Add, edit, and organize your contacts How contacts link to your communications # Credits & Billing Source: https://docs.bizzyco.ai/get-started/concepts/credits How Bizzy meters compute, charges for it, and protects you when you exceed your plan Bizzy charges for two things: **what you can build** (capacity) and **what you do with it** (usage). Both are denominated in credits, and both are governed by the **tier** your account is on. This page explains the model so the line items on your bill have a story behind them. ## What is a Credit? A **credit** is the unit of measurement for usage on top of your plan. **One credit equals one cent of overage cost.** Credits accumulate against your account when you exceed the allowances bundled into your tier; you settle them up by paying for credit packs (or letting auto-recharge do it for you). Inside your tier, you don't think about credits — you have an allowance and you use it. You only feel credits when you go past it. ## Tiers There are four tiers: * **Free** — try the platform, hard caps on capacity. * **Starter** — entry-level paid plan. * **Professional** — full-featured plan for active users. * **Enterprise** — custom limits, support SLA, negotiated pricing. Each tier defines two things: how much capacity you have (the **account objects**) and how much usage is included before overages kick in (the **consumables**). ## Account Objects (Capacity) Account objects are *how much you can have* — hard caps that don't accumulate. Five of them: | Object | What it limits | | --------------- | -------------------------------------------------------- | | **Businesses** | Number of businesses you can run inside the organization | | **Seats** | Number of users with access | | **Agents** | Number of AI agents you can configure | | **MCP Servers** | Number of MCP credentials/servers | | **Automations** | Number of active automations | If you hit the cap, you can't create more without upgrading. We don't bill overages for capacity — we just stop the meter. ## Consumables (Usage) Consumables are *how much you can do* — meters that reset on each billing cycle. Five of them: | Consumable | What it counts | | ----------------- | -------------------------------------------------------- | | **LLM Tokens** | Language model tokens consumed by agents and automations | | **Email Sends** | Outbound emails | | **SMS** | SMS messages, sent and received | | **Voice Minutes** | Voice call minutes | | **Storage** | Bytes stored in your file library | Inside your tier's allowance, these are free. Past it, every increment is billed at your tier's overage rate. API and MCP requests are not consumables. They are entitled by request rate rather than a monthly allocation, so they are never metered against an allowance and never billed per call — see [Usage](/admin-guide/billing/usage) and [Rate limits](/api-reference/rate-limits). ## Tier-Based Overage Rates Higher tiers get cheaper marginal usage: | Consumable | Free | Starter | Professional | | -------------------------- | ------ | ------- | ------------ | | **LLM Tokens** (per 10k) | \$0.50 | \$0.40 | \$0.30 | | **Email Sends** (per 100) | \$0.15 | \$0.10 | \$0.05 | | **SMS** (per 10) | \$0.15 | \$0.10 | \$0.075 | | **Voice Minutes** (per 10) | \$0.30 | \$0.20 | \$0.15 | | **Storage** (per GB) | \$0.25 | \$0.15 | \$0.10 | Enterprise rates are negotiated separately. ## How LLM Usage Becomes Credits The most common source of overage in active accounts is the **LLM Tokens** meter — every message your agents and automations send to a model counts. The relationship is direct: 1. Each LLM call records the input and output tokens consumed. 2. Tokens roll up into the `llmTokens` consumable on your account. 3. Once you cross your tier's included token allowance, additional tokens are billed at your tier's overage rate (e.g., \$0.30 per 10k on Professional). 4. The dollar charge is converted into credits — \$1 of overage = 100 credits. In other words: **credits are how the bill arrives**, not how the meter ticks. ## Recharging There are two ways to top up: * **Credit packs.** One-time purchases at $10, $20, $50, or $100. Use them when you know you have a busy month coming. * **Auto-recharge.** When your credit balance dips below a threshold, Bizzy tops it up automatically — the default top-up is **\$20**. Turn it on once and you stop thinking about it. Both buy the same credits; only the trigger differs. ## When You Downgrade — Soft Disable Bizzy never deletes your work because you change tiers. If you downgrade to a tier whose **account-object** caps are below your current usage, the platform doesn't throw away your extra agents, automations, or seats — it **soft-disables** them. Soft-disabled means: * The item is paused and marked as disabled due to the downgrade. * Newest entries are disabled first; **the organization owner is never disabled**. * The data is intact — it just can't run. * Move back up a tier (or remove other items) and you can re-activate them with one click; the platform verifies you're under the cap before allowing it. This is deliberate: downgrade decisions get reversed all the time, and losing the work each time would be punitive. ## Related Topics Detailed tier comparison See your current usage Buy credit packs and configure auto-recharge View, download, and pay invoices in-app # Files & Knowledge Source: https://docs.bizzyco.ai/get-started/concepts/files How Bizzy ingests, indexes, and retrieves your files for agents Bizzy lets you upload files — contracts, invoices, product sheets, runbooks — and makes them searchable by your agents. This page covers what happens between "I dropped a PDF in" and "my agent quoted the right paragraph back to me." ## What is a File? A **file** is any artefact you've uploaded to your organization. Each file: * Is stored securely in Bizzy storage. * Belongs to an organization, optionally inside a **folder**. * Has metadata — filename, content type, size, tags, description. * Has an **indexing status** that tracks whether it's searchable yet. Today, the indexing pipeline reads these formats end-to-end via OCR: **PDF**, **Word** (`.docx`), **PowerPoint** (`.pptx`), and **OpenDocument** text and presentations (`.odt`, `.odp`), plus the images **PNG**, **JPEG**, and **WebP** — alongside inline **Markdown** and other plain-text formats. Spreadsheets and other formats can still be uploaded and shared via public links — they simply aren't indexed for retrieval. ## Folders Files can be grouped into folders. Folders are useful for two reasons: 1. **Organisation.** Same as folders anywhere — group what belongs together. 2. **Agent access control.** Each file (and each folder) carries an **Agent access** flag. Turn the flag off on a folder and your agents will not see anything in it during retrieval, even if a query would otherwise match. This matters more than it sounds: it's how you separate, say, your public sales collateral from internal HR documents when both are in the same organization. ## From Upload to Searchable When a file is uploaded, an automatic pipeline takes it from raw bytes to retrievable knowledge: 1. **Store.** The file is saved and appears in your file list immediately. 2. **Extract.** PDFs, office documents (Word, PowerPoint, OpenDocument), and images are converted to clean, structured text via OCR. Markdown and other text files are read directly. 3. **Chunk.** The text is split along its natural structure — sections, paragraphs, sentences — so each piece stays coherent on its own, with a little overlap between neighbouring pieces so context isn't lost at boundaries. 4. **Index.** Each piece is indexed for both semantic (meaning-based) search and keyword search. A file's indexing status walks through `pending → indexing → indexed`. If a file isn't indexable (unsupported format, too large, or its text couldn't be extracted) the status ends in `skipped`, `excluded`, or `failed` — visible on the file's detail view so you know it's not searchable. ## How Agents Retrieve Files (RAG) When an agent needs information from your files, Bizzy uses **hybrid retrieval**: a semantic search that is good at fuzzy, meaning-level matches, and a keyword search that is good at exact terms — run together, with the best-matching passages from both handed to the agent as context. You get relevant results whether you ask "what's our refund policy?" or search for an exact part number. Two important guarantees are enforced on every retrieval: * Only content from the agent's own organization is ever returned. * Files (and folders) with **Agent access** turned off, files that aren't fully indexed, and files that have been deleted are silently excluded. Your agent never sees what you've told it not to see. ## What it Costs File usage is metered through two of your account's consumables: * **Storage** — the total bytes in your file library, counted against your tier's storage allowance. * **LLM Tokens** — indexing a file consumes embedding tokens, which count toward the same token allowance your agents and automations use. Both are included in your tier's allowance and charged at the relevant overage rate beyond it. See the [Credits](/get-started/concepts/credits) page for how the meters and tiers fit together. ## Related Topics How to add files in the web app Re-index files, exclude folders, troubleshoot How agents use files at runtime What storage and indexing cost # Core Concepts Source: https://docs.bizzyco.ai/get-started/concepts/index Understand the fundamental concepts behind Bizzy Before diving deeper into Bizzy, it helps to understand the key concepts that shape how the platform works. This section covers the building blocks of Bizzy: how data is organized, how communication flows, how AI does work for you, and how it all gets paid for. ## Key Concepts Multi-tenancy, members, and access People you communicate with and people who buy from you Multiple businesses inside one organization Email, SMS, and other channels in one inbox Work tracking and the Eisenhower priority matrix File ingestion, RAG indexing, and retrieval Conversational AI workers — and how they differ from automations Event-triggered AI workflows Tiers, consumables, overage rates, and credits ## How It All Fits Together Bizzy is built around a simple hierarchy: ```mermaid theme={null} graph TD A[Organization] --> B[Members] A --> Bus[Businesses] A --> D[Contacts] A --> E[Customers] A --> G[Automations] A --> Ag[Agents] A --> Tk[Tasks] A --> Fl[Files] Bus --> C[Email Addresses
& Phone Numbers] D --> H[Messages] E --> I[Transactions] B[Members
users with access] Bus[Businesses
commercial entities you run] C[Email & Phone
channels for sending and receiving] D[Contacts
people you communicate with] E[Customers
buyers and ongoing relationships] G[Automations
event-triggered workflows] Ag[Agents
conversational AI workers] Tk[Tasks
work to be done] Fl[Files
indexed documents agents can search] H[Messages
communications with contacts] I[Transactions
sales and purchases] ``` **Organizations** are the top-level container. Everything else belongs to an organization and is isolated from other organizations. **Members** are users with access to the organization. Each member has a role that determines their permissions. **Businesses** are the commercial entities you run *inside* the organization. Most accounts have one; agencies and holding companies often have several. Each business has its own profile, offerings, locations, and Stripe connection. **Email Addresses** and **Phone Numbers** are the connected channels Bizzy uses to send and receive communications — Google or Microsoft accounts for email, purchased numbers for SMS and voice. **Contacts** represent the individuals you communicate with. **Customers** are contacts you have a commercial relationship with. **Messages** are the communications themselves, grouped into threads. **Tasks** are units of work — created by you, by automations, or by agents — and surface on your home page through the Eisenhower priority matrix. **Files** are documents you upload. Once indexed, they become a knowledge base that agents can search via hybrid retrieval (vector + keyword). **Agents** are conversational AI workers you chat with: configured persona, tool access, conversation history. **Automations** are event-triggered workflows that run on their own. Most users mix them up at first — see the [Agents](/get-started/concepts/agents) page for when to reach for which. **Credits** are how usage on top of your plan is metered and billed. They don't appear in the hierarchy because they're not data — they're the meter that runs over everything. ## Start Learning If you're new, read these in order: Start here — how access and data isolation works The people side of the platform The most important distinction in Bizzy How tiers, consumables, and overages work # Messages & Threads Source: https://docs.bizzyco.ai/get-started/concepts/messages How Bizzy organizes communications across channels Bizzy unifies your business communications into a single inbox. This page explains how messages are organized, what channels are supported, and how threading works. ## Message Basics A **message** is any communication sent or received through Bizzy. Each message has: | Property | Description | | ---------------- | -------------------------------------- | | **Direction** | Incoming (received) or outgoing (sent) | | **Timestamp** | When the message was sent or received | | **Sender** | Who sent the message | | **Recipient(s)** | Who received the message | | **Content** | The message body and any attachments | | **Thread ID** | Groups related messages together | ## Supported Channels Bizzy supports multiple communication channels: | Channel | Description | | --------- | -------------------------- | | **Email** | Gmail, Outlook, Office 365 | | **SMS** | Text messages | Email is the primary channel. Connect your Google or Microsoft account from the **Email Addresses** page to start receiving messages. ## Email Messages Email messages include additional properties: | Property | Description | | --------------- | ---------------------------------- | | **Subject** | Email subject line | | **To/CC/BCC** | Recipients and their visibility | | **Headers** | Technical email headers | | **Labels** | Gmail labels or Outlook categories | | **Attachments** | Files attached to the email | ### Email Features * **HTML rendering** - Emails display with full formatting * **Attachment preview** - View images and documents inline * **Reply/Forward** - Respond directly from Bizzy * **Labels sync** - Gmail labels and Outlook categories are synced ## Threads A **thread** is a group of related messages. Threading helps you follow conversations without losing context. ### How Threading Works Bizzy groups messages into threads based on: 1. **Email headers** - The `In-Reply-To` and `References` headers 2. **Subject matching** - Messages with the same subject 3. **Participants** - Messages between the same people When you click a message in your inbox, you see the entire thread—all related messages in chronological order. ### Thread View The thread view shows: * All messages in the conversation * Newest messages at the bottom * Sender information for each message * Timestamps * Attachments You can reply from the thread view, and your response will be part of the same conversation. ## Inbox Organization Messages are organized into four views: ### Inbox Your main inbox shows messages that need attention: * Unread messages * Messages you haven't archived * Recent conversations ### Sent Messages you've sent, organized by date. ### Snoozed Messages you've temporarily hidden. Snoozed messages reappear at a time you choose: * Later today * Tomorrow * Next week * Custom date/time Snoozing is useful for messages you can't deal with right now but don't want to forget. ### Archived Messages you've filed away. Archived messages are: * Removed from your inbox * Still searchable * Still accessible in the Archived view * Not deleted ## Message Actions From any message, you can: | Action | Keyboard | Description | | ------------- | -------- | ----------------------- | | **Reply** | `R` | Send a response | | **Reply All** | `A` | Reply to all recipients | | **Forward** | `F` | Send to someone else | | **Archive** | `E` | Move to archived | | **Snooze** | `H` | Hide temporarily | | **Delete** | `#` | Move to trash | ## Searching Messages Find messages using the search bar in the header. You can search by: * **Content** - Words in the message body * **Sender** - Email address or name * **Subject** - Email subject line * **Date** - Messages from a specific time period * **Attachments** - Messages with files Example searches: * `from:john@example.com` - Messages from John * `subject:invoice` - Messages with "invoice" in the subject * `has:attachment` - Messages with attachments * `after:2024-01-01` - Messages after a specific date * `before:2024-12-31` - Messages before a specific date * `from:john has:attachment` - Combine multiple filters ## Message and Contact Linking Messages are automatically linked to contacts: 1. When a message arrives, Bizzy checks the sender's email 2. If a contact exists with that email, the message is linked 3. Click the contact name to see their full profile This means you can: * View all messages with a contact from their profile * See contact details directly from a message * Quickly create contacts from message senders ## Related Topics Detailed email management guide How contacts work with messages # Organizations Source: https://docs.bizzyco.ai/get-started/concepts/organizations How multi-tenancy and team access work in Bizzy Organizations are the foundation of Bizzy's data model. Every piece of data — contacts, messages, automations — belongs to an organization. This page explains what organizations are, why they exist, and how they shape the way you use Bizzy. ## What is an Organization? An organization is a container that holds all your Bizzy data. Think of it as a workspace that can represent: * Your company * A department or team * A personal account * A client you manage Each organization is completely isolated from others. Data in one organization cannot be accessed from another, even by the same user. ## Why Organizations? Organizations exist to solve a fundamental problem: keeping different contexts separate while letting the right people collaborate within each one. | Benefit | Description | | ----------------------- | ----------------------------------------------------------- | | **Data isolation** | Keep different businesses or clients completely separate | | **Team collaboration** | Share access with colleagues while controlling permissions | | **Resource management** | Connect different email accounts to different organizations | | **Billing separation** | Each organization can have its own subscription | For example, a freelancer managing three clients can create a separate organization for each — keeping contacts, messages, and automations completely isolated. A single company would typically use one organization with multiple members. ## Members and Roles Organizations can have multiple members. Each member has a role that determines what they can do: | Role | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------- | | **Owner** | Full access to everything, including billing, API keys, and member management. Every organization has at least one owner. | | **Admin** | Can manage data and invite members, but cannot access billing or API keys. | | **User** | Read-only access to organization data. Can manage their own profile and files. | This hierarchy follows the principle of least privilege — most team members only need the User or Admin role. See [Roles & Permissions](/admin-guide/organization/permissions) for the full permission matrix. ## Organization Scope Everything in Bizzy is scoped to an organization: * **Contacts and customers** belong to an organization * **Messages** are received and sent through the organization's connected resources * **Automations** run within the organization's context * **API keys** and **MCP server access** grant access to a single organization's data If you belong to multiple organizations, you can switch between them from the header. Each switch changes your entire view to that organization's data. ## How Organizations Relate to Accounts Your Bizzy **account** is your personal identity — your login credentials. **Organizations** are workspaces you belong to. The relationship works like this: * One account can belong to multiple organizations * One organization can have multiple accounts (members) * Billing is managed at the account level, covering all organizations under it * Your subscription tier determines how many organizations you can create ## Related Topics Create and configure an organization Invite members, assign roles, and manage access Full permission matrix for each role # Tasks Source: https://docs.bizzyco.ai/get-started/concepts/tasks How tasks work in Bizzy and the priority matrix that powers your home page A **task** is a unit of work tracked inside Bizzy — something that needs doing, by someone, at some point. Tasks can be created by you, by an agent, or by an automation, and they all surface in the same place: the priority matrix on your home page. ## Anatomy of a Task | Property | Description | | --------------- | -------------------------------------------------------------------------------------------------- | | **Title** | Short summary of what needs doing | | **Description** | Optional longer detail | | **Status** | Where the task is in its lifecycle | | **Importance** | How significant the task is — `low`, `medium`, `high` | | **Urgency** | How time-sensitive the task is — `low`, `medium`, `high` | | **Category** | Type of work — bug fix, feature request, meeting, planning, research, review, documentation, other | | **Due date** | Optional deadline | | **Assignees** | Members of the organization responsible for the task | ### Status Lifecycle Tasks move through a small set of states: ``` backlog → todo → in_progress → in_review → done ↘ cancelled ``` You can jump between states freely — the order is suggestive, not enforced. ## The Eisenhower Priority Matrix Bizzy uses the **Eisenhower matrix** as the model for prioritising work. The idea, popularised by Dwight Eisenhower's "what is important is seldom urgent and what is urgent is seldom important," is to plot tasks on two axes — urgency and importance — and act differently in each quadrant. | | Important | Not important | | -------------- | ----------------- | ----------------- | | **Urgent** | **Q1 — Do First** | **Q3 — Delegate** | | **Not urgent** | **Q2 — Schedule** | **Q4 — Don't Do** | Bizzy maps each task to a quadrant using a deliberately strict rule. Only `high` counts as **urgent** or **important** — `low` and `medium` are treated equally as "not". And tasks with `null` urgency or `null` importance are routed straight to Q1, regardless of the other axis, so unclassified work can't slip past you without being triaged. * **Q1 — Do First.** Urgent and important. The fire-fighting quadrant. * **Q2 — Schedule.** Important but not urgent. Where deep work belongs — block time for it. * **Q3 — Delegate.** Urgent but not important. Hand off if you can; otherwise batch. * **Q4 — Don't Do.** Neither urgent nor important. Cut, archive, or politely ignore. ## The Home Page Widget Your organization home page leads with the priority matrix widget. It pulls together up to **50 tasks** plus up to **25 unread messages** and groups them into the four quadrants, sorted by due date and then creation time. You can flip between a 2×2 grid and a flat list, and act on items inline without leaving the page. Messages appear in the matrix because in a communications-driven business, an unread email is often a task in disguise. Treating both as items on the same grid means the AI's triage of incoming mail flows directly into your work queue. ## Where Tasks Come From Tasks are first-class entities — anything that produces work can produce a task: * **People.** You create tasks manually for things you need to track. * **Automations.** A rule like "when a customer asks for a refund, create a task for the billing team" emits a task. * **Agents.** When an agent is given the `createTask` tool and decides a follow-up is required, it can create one. Tasks created this way are flagged so you can audit them. Assignees are members of your organization. A task can have multiple assignees — useful for things one person owns but several people need to follow. ## Related Topics How to create, edit, and triage tasks in the web app Tour of the home-page priority matrix How automations create tasks for you How agents work with tasks # Welcome to Bizzy Source: https://docs.bizzyco.ai/get-started/index The AI-powered platform for unified business communications Bizzy brings all your business communications into one intelligent platform. Manage emails, contacts, customers, and automate workflows with AI—all from a single dashboard. ## What is Bizzy? Bizzy is a unified business communication platform that helps teams: * **Centralize communications** - Manage emails from multiple providers (Google, Microsoft) in one inbox * **Organize contacts** - Keep track of contacts, customers, and business relationships * **Automate workflows** - Create intelligent automations triggered by incoming messages * **Leverage AI** - Use AI agents to process, categorize, and respond to communications Whether you're a solo professional or part of a larger team, Bizzy helps you stay organized and responsive. ## Key Features View and manage emails from all your connected accounts in one place. Organize with folders, labels, and smart filters. Store contact details, track customer relationships, and link communications to the right people. Create workflows that trigger automatically based on incoming messages, saving time on repetitive tasks. Deploy AI agents that can read, categorize, and help manage your communications intelligently. ## Choose Your Path **New to Bizzy?** Start with the quickstart guide to connect your first email and explore the platform. **Managing a team?** Learn how to set up your organization, invite members, and configure integrations. **Building integrations?** Explore the API reference to programmatically access your data. ## Getting Help If you need assistance: * **Documentation** - Browse the guides in the sidebar for detailed instructions * **Support** - Email us at [support@bizzyco.ai](mailto:support@bizzyco.ai) * **Status** - Check [status.bizzyco.ai](https://status.bizzyco.ai) for system status ## Next Steps Set up your account and connect your email Build an AI-powered support workflow from scratch Learn your way around the dashboard # Platform Overview Source: https://docs.bizzyco.ai/get-started/overview Navigate the Bizzy dashboard and discover key features This guide introduces you to the Bizzy platform interface, helping you find your way around and understand where to access different features. ## Dashboard Layout The Bizzy dashboard is organized into three main areas: 1. **Sidebar** - Navigation menu on the left for accessing different sections 2. **Main Content** - The central area where you work with messages, contacts, and other data 3. **Header** - Top bar with organization switcher, search, and account settings ## Sidebar Navigation The sidebar provides quick access to all major features. Here's what each section does: ### Home Your dashboard landing page. For new organizations this is also where the **Setup checklist** card lives — a seven-step walkthrough (business profile, email, domain, phone, contact, automation, team invite) that auto-completes as you create each entity and silently disappears once every task is done or dismissed. ### Inbox Your unified email inbox. This is where you'll spend most of your time managing communications. | View | Description | | ------------ | ----------------------------------------------------- | | **Inbox** | Unread and active messages requiring attention | | **Sent** | Messages you've sent | | **Snoozed** | Messages you've temporarily hidden to deal with later | | **Archived** | Messages you've filed away for reference | Click any message thread to open the full conversation. The thread view shows all related messages in chronological order. ### Contacts Manage your contact database. Store names, email addresses, phone numbers, and notes about the people you communicate with. * View all contacts in a searchable list * Click a contact to see their full profile and communication history * Create, edit, and delete contacts ### Email Addresses Manage the email accounts Bizzy sends and receives on behalf of. Connect Google (Gmail) or Microsoft (Outlook / Office 365) via OAuth, or create an address on a verified custom domain. From this page you can view sync status, pause or disconnect an account, and update provider settings. ### Phone Numbers Buy and manage phone numbers for SMS and voice. The page shows connected numbers, their messaging capabilities, and recording and routing settings. ### Domains Manage custom email domains for your organization. This section handles: * Domain registration and verification * DNS configuration * WHOIS contact management Domain management is typically handled by administrators. See the [Organization Setup](/admin-guide/organization/setup) guide for details. ### Automations Create and manage automated workflows that respond to incoming messages. * View all automations and their status (active, paused, completed) * Create new automations with triggers, conditions, and actions * Monitor automation execution history ### Agents AI agents that can help process and respond to communications. * View configured agents * Monitor agent activity and conversations * Configure agent behavior and permissions ### Files Upload, store, and manage files within Bizzy. * Upload documents and attachments * Generate shareable links * Organize files into folders ## Header Bar The header bar at the top of the screen provides: ### Organization Switcher If you belong to multiple organizations, click the organization name in the header to switch between them. Each organization has its own: * Contacts and customers * Email resources * Automations and settings * Team members ### Search Use the search bar to quickly find: * Messages by content or sender * Contacts by name or email * Files by name ### Account Menu Click your profile icon to access: * Profile settings (name, email, timezone) * Organization settings * Sign out ## Working with Messages ### Thread View When you click a message in the inbox, it opens in thread view: * All messages in the conversation are shown chronologically * You can reply directly from the thread * Related contacts are linked automatically ### Message Actions From any message, you can: * **Reply** - Send a response * **Archive** - Move to archived messages * **Snooze** - Hide temporarily and resurface later * **Delete** - Remove permanently ## Mobile Access Bizzy is a responsive web application that works on tablets and mobile devices. While there's no dedicated mobile app, you can: * Access the full platform from your mobile browser * Add Bizzy to your home screen for app-like experience * Receive notifications if enabled in your browser For the best experience on mobile, use a modern browser like Chrome or Safari. ## Next Steps Learn about organizations, contacts, and messages Connect email and manage your inbox # Quickstart Source: https://docs.bizzyco.ai/get-started/quickstart Get up and running with Bizzy in 5 minutes This guide walks you through setting up Bizzy and connecting your first email account. By the end, you'll have a working inbox ready to manage your business communications. ## Prerequisites Before you begin, you'll need: * A Google or Microsoft email account to connect * A modern web browser (Chrome, Firefox, Safari, or Edge) ## Step 1: Create Your Account Go to [bizzyco.ai](https://www.bizzyco.ai) and click **Get Started** or **Sign In**. Create an account using your email address or sign in with Google/Microsoft. If you signed up with email, check your inbox for a verification link and click it to confirm your account. Review and accept the Terms of Service and Privacy Policy to finish creating your account. If we make material updates to these documents later, you may be asked to review and accept them again at your next sign-in. ## Step 2: Create an Organization Organizations are how Bizzy groups users and data. Every account needs at least one organization. After signing in for the first time, you'll be prompted to create an organization. Enter a name (e.g., your company name or "Personal"). Click **Create** to finish. You'll be taken to your new organization's dashboard. You can create multiple organizations later if you need to separate work and personal communications, or manage different businesses. ## Step 3: Work Through the Setup Checklist Your new organization's home page shows a **Setup checklist** card with the seven steps that turn a blank workspace into a working AI-powered inbox: 1. Complete your business profile 2. Connect your email 3. Add a custom domain 4. Connect a phone number 5. Add your first contact 6. Set up your first automation 7. Invite your teammates Each task auto-completes when you do the thing it asks for (for example, connecting an email provider completes "Connect your email"). When every task is complete or dismissed, the card silently disappears from the home page. You don't have to complete all seven today — this quickstart walks through the two that unlock the rest of the platform: connecting email and adding a contact. Everything else can wait until you need it. ## Step 4: Connect Your Email The **Connect your email** task is the first CTA on the checklist. On the home page, click **Connect email** on the Setup checklist. This takes you to the **Email Addresses** page. Click **Connect email** and select your provider (Google or Microsoft). You'll be redirected to Google or Microsoft to authorize Bizzy. Review the permissions and click **Allow** or **Accept**. Bizzy begins syncing your recent emails. This takes a few minutes depending on your inbox size. Bizzy uses OAuth — your credentials are never seen or stored. You can revoke access at any time from your provider's security settings. Once the email address is created, the **Connect your email** checklist task auto-completes. ## Step 5: Explore Your Inbox Once your email is connected, your messages appear in the inbox. Click **Inbox** in the sidebar to view your messages. Messages are organized into threads. Click any thread to view the full conversation. Use the tabs to switch between **Inbox**, **Sent**, **Snoozed**, and **Archived** messages. ## Step 6: Add Your First Contact Back on the home page, the next expanded task is **Add your first contact**. Click **Add contact** on the Setup checklist to jump to the **Contacts** page. Click **Add Contact** and fill in the details: name, email, phone number, and any notes. Click **Save**. The **Add your first contact** task auto-completes, and the home checklist moves the next incomplete task into the expanded slot. ## What's Next? You've successfully set up Bizzy! The next step is to see what makes Bizzy different — AI-powered automations. Build a working AI-powered support workflow from scratch — the best way to see Bizzy in action Understand how organizations, contacts, and automations fit together Learn your way around all the features in the dashboard Add colleagues to your organization ## First Steps Checklist Use this checklist to make sure you've completed the basics: * [ ] Created your Bizzy account * [ ] Set up your first organization * [ ] Completed the **Connect your email** setup task * [ ] Explored the inbox and viewed messages * [ ] Completed the **Add your first contact** setup task Need help? Contact us at [support@bizzyco.ai](mailto:support@bizzyco.ai) or check the rest of this documentation for detailed guides. # Tutorial: Handle Your First Support Email with AI Source: https://docs.bizzyco.ai/get-started/tutorial Build a working AI-powered support workflow from scratch in Bizzy In this tutorial, you'll set up Bizzy to automatically handle incoming support emails using AI. By the end, you'll have a working automation that acknowledges support requests, extracts key details, and saves the sender as a contact — all without you lifting a finger. This is how Bizzy is designed to work: you connect your communications, tell the AI what to do in plain English, and let it handle the rest. ## What you'll build You'll create a complete support email workflow that: 1. Detects incoming emails that look like support requests 2. Sends an immediate, personalized acknowledgment to the sender 3. Saves the sender as a contact if they're new By the end, you'll understand how Bizzy's core features — email, contacts, and automations — work together. ## Prerequisites * A Google or Microsoft email account you can use for testing * A modern web browser (Chrome, Firefox, Safari, or Edge) ## Step 1: Create your account and organization First, let's get you set up on Bizzy. Go to [bizzyco.ai](https://www.bizzyco.ai) and click **Get Started**. Create an account using your email or sign in with Google/Microsoft. After signing in, you'll be prompted to create an organization. Enter a name — this can be your company name, or something like "My Business" if you're just exploring. Click **Create**. You're now on your organization's dashboard. This is your home base — everything you do in Bizzy happens within this organization. The **Setup checklist** card lists the seven steps that get a new org ready; we'll complete two of them (connect your email, create an automation) as part of this tutorial. ## Step 2: Connect your email The **Connect your email** task is the first CTA on the Setup checklist. On the home page, click **Connect email** on the Setup checklist. This takes you to the **Email Addresses** page. Click **Connect email** and select your provider (Google or Microsoft). You'll be redirected to your provider to authorize Bizzy. Review the permissions and click **Allow** (Google) or **Accept** (Microsoft). Bizzy begins syncing your recent emails. This takes a few minutes depending on your inbox size. The address appears on the **Email Addresses** page with a sync indicator. Bizzy uses OAuth — it never sees or stores your email password. You can revoke access at any time from your provider's settings. Once the email address is created, the **Connect your email** setup task auto-completes. Once sync completes, click **Inbox** in the sidebar. You should see your recent emails. Take a moment to click through a few threads — this is the unified inbox where all your connected accounts appear together. ## Step 3: Create your first automation Now for the interesting part. You'll tell Bizzy to watch for incoming emails and respond to them using AI. Click **Automations** in the sidebar, then click **Create Automation**. Enter a descriptive name: **Support Email Auto-Acknowledgment**. Good names make it easy to find and manage your automations later. For the trigger event, enter: **New email received**. This tells Bizzy to run the automation every time an email arrives. This is where you tell the AI what to do — in plain English. Paste the following into the instructions field: ``` When a new email arrives: 1. If the email looks like a support request or question about our services, send a friendly acknowledgment reply: - Thank them for reaching out - Confirm we received their message - Let them know we'll respond within 24 hours - Keep the tone warm and professional - Keep the reply under 100 words - Sign off with "Best regards" and "The Support Team" 2. If the email is clearly not a support request (newsletters, marketing, automated notifications), do nothing. ``` Click **Save**. The automation is enabled by default and starts working immediately. Saving also auto-completes the **Set up your first automation** task on the home checklist. ## Step 4: Test it Let's see your automation in action. From a different email account (or ask a friend), send an email to the address you connected. Write something that looks like a support request, for example: > Subject: Help with my account > > Hi, I'm having trouble logging in to my dashboard. I keep getting an "invalid credentials" error even though I'm sure my password is correct. Can you help? Wait a minute or two, then check the **Inbox** in Bizzy. You should see: * The incoming support email in your inbox * An outgoing reply that the AI generated and sent automatically Click the thread to see the full conversation. The AI's reply should be a friendly acknowledgment that follows your instructions — thanking the sender, confirming receipt, and setting expectations. If the automation didn't trigger, check a few things: Is the automation enabled? (Look for the toggle on the Automations page.) Did the email finish syncing? Give it another minute and check the automation's execution history for any errors. ## Step 5: Check the results Let's verify everything worked end-to-end. Go to **Automations**, click your automation, and look at the execution history. You should see a successful execution with details about what the AI did. Click **Contacts** in the sidebar. If the sender was new, Bizzy may have automatically created a contact record for them. Click the contact to see their profile and the linked message history. ## What you've accomplished You've built a working AI-powered support workflow. Here's what's happening behind the scenes every time an email arrives: 1. Bizzy receives the email through your connected account 2. The automation detects a new message and triggers 3. The AI reads the email and evaluates your instructions 4. If it's a support request, the AI composes and sends a reply 5. The sender and message are linked in your contact database This is the core loop of Bizzy: **connect → automate → let AI handle it**. Every feature builds on this pattern. ## Next steps Now that you've seen Bizzy in action, here are some ways to go further: Learn how to fine-tune triggers, add conditions, and write better AI instructions Learn how organizations, contacts, messages, and automations fit together Organize your contacts with labels, notes, and detailed profiles Give AI assistants like Claude direct access to your Bizzy data # Authentication Source: https://docs.bizzyco.ai/mcp-server/authentication How AI agents authenticate to the Bizzy MCP server The Bizzy MCP server is a protected resource. Clients authenticate using **OAuth 2.1 with PKCE and Dynamic Client Registration (RFC 7591)**, following the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). Modern MCP clients — Claude Desktop, Claude Code, Cursor, Windsurf, and the MCP Inspector — run the entire flow automatically. As an end user you only need to: 1. Point the client at `https://mcp.bizzyco.ai`. 2. Sign in to Bizzy when the consent screen opens in your browser. 3. Approve the consent screen, choosing which tool categories the client may use. The rest of this page describes the flow in detail for client developers and for anyone debugging a connection. ## How the flow works ``` Client → /mcp (or /sse) (no token) Server → 401 + WWW-Authenticate Client → /.well-known/oauth-protected-resource/mcp (route-scoped; host-level also available) Client → /.well-known/oauth-authorization-server Client → POST /oauth/register (Dynamic Client Registration) Client → /oauth/authorize (browser, with PKCE code_challenge) User → consent screen Server → redirect with auth code Client → POST /oauth/token (code + code_verifier) Server → access_token (+ refresh_token if offline_access) Client → /mcp or /sse (Authorization: Bearer ) ``` The handshake is plain OAuth 2.1; no Bizzy-specific extensions are involved. ## Discovery The server publishes two host-derived metadata documents. A client discovers everything else from these. | Endpoint | Purpose | | ----------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `/.well-known/oauth-protected-resource` | RFC 9728 protected-resource metadata. Lists the authorization server. | | `/.well-known/oauth-authorization-server` | RFC 8414 authorization-server metadata. Lists `/oauth/register`, `/oauth/authorize`, `/oauth/token`, supported scopes, and PKCE methods. | You can fetch them directly: ```bash theme={null} curl -s https://mcp.bizzyco.ai/.well-known/oauth-protected-resource | jq curl -s https://mcp.bizzyco.ai/.well-known/oauth-authorization-server | jq ``` ## 401 response shape A request to `/mcp` or `/sse` without a valid Bearer token returns HTTP `401` with a `WWW-Authenticate` header pointing back to a route-scoped protected-resource metadata URL on the same host: ```http theme={null} HTTP/1.1 401 Unauthorized WWW-Authenticate: Bearer realm="OAuth", resource_metadata="https://mcp.bizzyco.ai/.well-known/oauth-protected-resource/mcp", error="invalid_token", error_description="Missing or invalid access token" Content-Type: application/json {"error":"invalid_token","error_description":"Missing or invalid access token"} ``` The 401 — not a JSON-RPC error envelope — is the canonical signal that the client should run discovery and the OAuth flow. The `resource_metadata` URL is route-scoped (`/mcp` and `/sse` advertise their own metadata documents); a host-level document is also available at `/.well-known/oauth-protected-resource` for clients that prefer it. ## Dynamic Client Registration Clients register themselves at `POST /oauth/register` per RFC 7591. Registration is open (no admin approval required) but rate-limited to **10 requests per 60 seconds per IP**, so clients should cache the returned `client_id` (and any `client_secret`) and reuse it across launches rather than re-registering every time. Prefer the OS credential store (Keychain on macOS, Credential Manager on Windows, libsecret on Linux) over a plaintext file on disk, especially for `client_secret` values. ## PKCE The server requires PKCE on every authorization request and only accepts the `S256` code-challenge method. Plain PKCE is rejected — clients that send `code_challenge_method=plain` will fail the authorize step. ## Resource indicator The server requires an RFC 8707 `resource` parameter on every authorization request, and its value must identify this MCP server (the same origin you connect to, e.g. `https://mcp.bizzyco.ai`). This binds the issued access token's audience to Bizzy so it can't be replayed against another server. An authorize request that omits `resource`, or sends one pointing at a different origin, is rejected with an `Invalid resource` error. Modern MCP clients derive this from the server URL and send it automatically; custom clients must include it. ## Scopes Two scopes are advertised: | Scope | Required | Purpose | | ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `mcp` | Yes | Access to the MCP transport endpoints. | | `offline_access` | No | Issues a refresh token alongside the access token. Request only for persistent or background clients; omit for interactive one-shot use, since the 90-day refresh token is a longer-lived credential. | During consent the user also chooses which tool categories the client may call. The set of tools advertised over `tools/list` is filtered against that selection on every request. ## Token lifetime | Token | TTL | Notes | | ------------- | ------- | -------------------------------------------------------------- | | Access token | 60 min | Bearer token presented on `/mcp` and `/sse`. | | Refresh token | 90 days | Issued only when `offline_access` was granted; rotated on use. | Access tokens are refreshed via `POST /oauth/token` with `grant_type=refresh_token`. Refresh tokens rotate on every use per OAuth 2.1. The token endpoint is rate-limited to **10 requests per 60 seconds per IP**; cache the access token for its lifetime rather than re-exchanging on every call. ## Rate limits Two limits apply to authenticated traffic, and they surface differently. ### Tool calls: your plan's per-minute limit Every `tools/call` spends one request from your account's MCP allowance: | Plan | MCP requests per minute | | ------------ | ----------------------- | | Free | 10 | | Starter | 30 | | Professional | 100 | | Enterprise | 300 | The limit is also the burst capacity: you can spend your full per-minute allowance at once, and it replenishes continuously over the following minute. MCP and API allowances are independent — heavy API traffic never consumes your MCP capacity. See [Understanding Limits](/admin-guide/billing/limits) for how rate limits fit into your plan. A throttled tool call is **not** an HTTP error. The request succeeds at the transport level and the throttle is reported in the JSON-RPC envelope, so clients must inspect the response body rather than the status code alone: ```json theme={null} { "jsonrpc": "2.0", "id": 1, "error": { "code": -32004, "message": "Rate limit exceeded", "data": { "retryAfter": 6 } } } ``` Wait `data.retryAfter` seconds before retrying that call. Other methods (`tools/list`, `ping`, and the rest of the protocol) do not spend from this allowance. ### Transport: per-(user, client) backstop Independently, `/mcp` and `/sse` accept at most **600 requests per 60 seconds per (user, client)** as an abuse backstop. Its ceiling sits above every plan's tool-call limit, so ordinary use never reaches it. A throttled request here is HTTP `429` with the same JSON-RPC error body and a `Retry-After` header. The server does not emit `X-RateLimit-*` headers on either surface. ## Reference * [MCP authorization spec (2025-06-18)](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization) * [RFC 9728 — OAuth 2.0 Protected Resource Metadata](https://datatracker.ietf.org/doc/html/rfc9728) * [RFC 8414 — OAuth 2.0 Authorization Server Metadata](https://datatracker.ietf.org/doc/html/rfc8414) * [RFC 7591 — Dynamic Client Registration](https://datatracker.ietf.org/doc/html/rfc7591) # Connection Guide Source: https://docs.bizzyco.ai/mcp-server/connection Connect AI agents to the Bizzy MCP server This guide covers how to connect AI agents to the Bizzy MCP server, including the available transports and troubleshooting common issues. ## Connection URL Point your client at the Streamable HTTP endpoint: ``` https://mcp.bizzyco.ai/mcp ``` Configure this full URL — including the `/mcp` path — rather than the bare domain. OAuth discovery lives at the domain root, so a client pointed at `https://mcp.bizzyco.ai` completes sign-in but then fails on its first request. The server now redirects MCP requests from the root to `/mcp` automatically, but configuring the endpoint directly is the most reliable. ## Authentication Modern MCP clients (Claude Desktop, Claude Code, Cursor, Windsurf) handle OAuth 2.1 + PKCE automatically — point them at the connection URL above and they walk you through sign-in and consent. See [Authentication](/mcp-server/authentication) for the full flow. ## Transports The MCP server supports two transports: * **Streamable HTTP** — `https://mcp.bizzyco.ai/mcp`. The current MCP transport; recommended for new clients. * **Server-Sent Events (SSE)** — `https://mcp.bizzyco.ai/sse`. Kept for compatibility with clients that implement the earlier SSE transport. Pick whichever your client supports; you do not need to configure both. ## Health Check Verify the MCP server is available before connecting: ```bash theme={null} curl https://mcp.bizzyco.ai/health ``` Response: ```json theme={null} { "status": "ok" } ``` The health check endpoint doesn't require authentication. Use it to verify connectivity before attempting to establish an authenticated connection. ## Troubleshooting **Possible causes:** * Network connectivity issues * Firewall blocking outbound HTTPS * Incorrect URL **Solutions:** 1. Verify network connectivity: `curl https://mcp.bizzyco.ai/health` 2. Check firewall rules allow outbound HTTPS (port 443) 3. Ensure you're using `https://` not `http://` If the browser consent flow completes but your client reports a failure (often `HTTP 405`) on its first request, the client is almost certainly pointed at the domain root instead of the transport endpoint. OAuth discovery lives at the root, so sign-in succeeds and only the first transport request reveals the wrong path. **Solution:** set your connection URL to the explicit endpoint — `https://mcp.bizzyco.ai/mcp` (or `https://mcp.bizzyco.ai/sse`). The server redirects MCP requests from the root to `/mcp` automatically, but configuring the endpoint directly is the most reliable. A 401 is the canonical signal that your client needs to run (or re-run) the OAuth flow. The `WWW-Authenticate` header on the response points to a route-scoped protected-resource metadata URL (e.g. `/.well-known/oauth-protected-resource/mcp`), which a spec-compliant client uses to start discovery. **Solutions:** 1. Confirm your client supports OAuth 2.1 + PKCE + Dynamic Client Registration. Most current MCP clients do. 2. Make sure you completed the consent screen in your browser. If you cancelled it, retry the connection from your client. 3. If the client looks stuck after a successful consent, remove and re-add the Bizzy server in the client so it re-registers via DCR. 4. See [Authentication](/mcp-server/authentication) for the full handshake. **Possible causes:** * Insufficient permissions for the requested tool * The tool's category wasn't granted during consent * Account suspended **Solutions:** 1. Check the error message for details 2. Re-run the consent screen from your client and grant the tool categories you need 3. Check your agent's permissions in the dashboard Throttling shows up in two different shapes — check the response body, not just the status code. **A tool call returns a JSON-RPC error with `code: -32004`.** You've spent your plan's per-minute MCP allowance (Free 10, Starter 30, Professional 100, Enterprise 300). The HTTP response is otherwise normal, so a client that only inspects status codes will miss this. **The request returns HTTP `429`.** You've hit the per-(user, client) transport backstop of 600 requests per 60 seconds — well above any plan's tool-call limit, so this usually means a runaway retry loop. **Solutions:** 1. Wait `data.retryAfter` seconds (JSON-RPC error) or the `Retry-After` header (HTTP 429) before retrying 2. Implement request queuing or throttling, with exponential backoff as a fallback 3. See [Rate limits](/mcp-server/authentication#rate-limits) for the full breakdown **Possible causes:** * Network instability * Idle timeout * Server maintenance **Solutions:** 1. Implement automatic reconnection logic 2. Send periodic ping messages to keep the connection alive 3. Check [status.bizzyco.ai](https://status.bizzyco.ai) for service issues ## Session Management MCP connections are stateful. Each connection receives a unique session ID that persists for the duration of the connection. * **Session IDs** are generated automatically on connection * **Sessions expire** after extended idle periods * **Reconnections** create new sessions - previous session state is not preserved Design your agent to be stateless where possible. Don't rely on server-side session state persisting between tool calls. ## Next Steps Explore the complete list of MCP tools See examples of MCP integrations # Claude Desktop Source: https://docs.bizzyco.ai/mcp-server/integrations/claude Connect Bizzy to Claude Desktop using MCP This guide walks you through connecting the Bizzy MCP server to Claude Desktop, allowing Claude to access your contacts, messages, and other business data directly. ## Prerequisites Before you begin, ensure you have: * [Claude Desktop](https://claude.ai/download) installed * A Bizzy account ## Connect Claude Desktop ships with native support for streamable-HTTP MCP servers and runs the OAuth 2.1 + PKCE handshake for you. The custom-connector UI used below requires a recent Claude Desktop build — if you don't see **Connectors** under **Settings**, install the latest version from [claude.ai/download](https://claude.ai/download). 1. Open Claude Desktop and go to **Settings → Connectors → Add custom connector**. 2. Paste the Bizzy MCP URL as the server URL: ``` https://mcp.bizzyco.ai ``` 3. Click **Connect**. Claude Desktop opens a browser tab on `https://mcp.bizzyco.ai/oauth/authorize`. 4. Sign in to Bizzy (if you aren't already), then review the consent screen — choose which tool categories Claude Desktop may use, and decide whether to grant `offline_access` for a long-lived refresh token. 5. Approve. The browser hands control back to Claude Desktop and the connector goes green. See [Authentication](/mcp-server/authentication) if you want to understand the OAuth handshake in detail. ## Verification Once the connection is working: 1. Open a new conversation in Claude Desktop 2. Ask Claude: "What Bizzy tools do you have access to?" 3. Claude should list the available tools based on your permissions ## Example Prompts Once connected, you can ask Claude to interact with your Bizzy data: | Task | Example Prompt | | ----------------- | -------------------------------------------------------------------------------------- | | Find a contact | "Find the contact information for John Smith" | | Search messages | "Show me recent messages about the project proposal" | | View conversation | "What's the full email thread with [support@example.com](mailto:support@example.com)?" | | Create a contact | "Add a new contact for Jane Doe at [jane@example.com](mailto:jane@example.com)" | ## Troubleshooting **Possible causes:** * The connector wasn't approved in the consent screen * Tool categories were unchecked during consent * The connector is showing red in **Settings → Connectors** **Solutions:** 1. Open **Settings → Connectors** and confirm the Bizzy connector is green. 2. If it's red, click **Reconnect** and re-approve the consent screen. 3. If it's green but Claude can't see specific tools, remove and re-add the connector — during consent, make sure the relevant tool categories are checked. If the consent screen fails to load, check that you can reach `https://mcp.bizzyco.ai/.well-known/oauth-protected-resource` from your machine and that you're signed in to Bizzy in the same browser Claude Desktop opened. If the connector goes red after a successful approval, remove and re-add it — Claude Desktop will register a fresh OAuth client via Dynamic Client Registration. ## Next Steps Explore all available MCP tools Learn about MCP server authentication # Cursor IDE Source: https://docs.bizzyco.ai/mcp-server/integrations/cursor Connect Bizzy to Cursor using MCP This guide walks you through connecting the Bizzy MCP server to Cursor IDE, allowing Cursor's AI to access your contacts, messages, and other business data while coding. ## Prerequisites Before you begin, ensure you have: * [Cursor IDE](https://cursor.com/) installed * A Bizzy account ## Connect Cursor supports streamable-HTTP MCP servers and runs the OAuth 2.1 + PKCE handshake for you. 1. Add Bizzy to your Cursor MCP config. Use `.cursor/mcp.json` in a project directory, or `~/.cursor/mcp.json` for every project: ```json theme={null} { "mcpServers": { "bizzy": { "url": "https://mcp.bizzyco.ai/mcp" } } } ``` You can also add the server through **File → Preferences → Cursor Settings → MCP**, which writes the same JSON. 2. Restart Cursor. 3. The first time Cursor calls a Bizzy tool — or when you click **Connect** in the MCP settings — Cursor opens a browser tab for OAuth. 4. Sign in to Bizzy and approve the consent screen. Cursor stores the access token and the tools become available in chat. See [Authentication](/mcp-server/authentication) for details on the OAuth handshake. ## Verification To verify the connection is working: 1. Open Cursor's AI chat (Cmd+L or Ctrl+L) 2. Ask: "What Bizzy tools do you have access to?" 3. Cursor should list the available tools ## Example Usage Once connected, you can use Bizzy tools in your development workflow: | Task | Example Prompt | | --------------------- | ---------------------------------------------------- | | Find contact info | "Look up the contact details for our main client" | | Search communications | "Find all messages about the API integration" | | Review history | "Show the conversation history with the design team" | ## Troubleshooting **Possible causes:** * Configuration file in wrong location * Invalid JSON syntax * Cursor not restarted **Solutions:** 1. Verify the configuration file path 2. Validate your JSON syntax 3. Completely restart Cursor (not just reload window) If the OAuth browser tab fails to load, check that you can reach `https://mcp.bizzyco.ai/.well-known/oauth-protected-resource` from your machine. If Cursor shows a stale token error, remove the `bizzy` entry from your `mcp.json`, restart Cursor, and re-add it — that forces a fresh Dynamic Client Registration. See [Authentication](/mcp-server/authentication) for the underlying flow. Cursor currently supports MCP tools but not MCP resources. This means you can call Bizzy tools (like `createContact`, `listMessages`) but cannot access read-only MCP resources that some servers provide. ## Next Steps Explore all available MCP tools Learn about MCP server authentication # Integrations Overview Source: https://docs.bizzyco.ai/mcp-server/integrations/index Connect the Bizzy MCP Server to AI coding tools The Bizzy MCP server integrates with popular AI-powered development tools, allowing you to access your business data directly from your preferred coding environment. ## Supported Tools | Tool | Platform | Configuration | | ------------------------------------------------- | --------------------- | --------------------- | | [Claude Desktop](/mcp-server/integrations/claude) | macOS, Windows | Settings → Connectors | | [Cursor](/mcp-server/integrations/cursor) | macOS, Windows, Linux | `.cursor/mcp.json` | | [Windsurf](/mcp-server/integrations/windsurf) | macOS, Windows, Linux | `mcp_config.json` | ## Authentication Each of the clients listed above runs the OAuth 2.1 + PKCE handshake automatically. Point the client at `https://mcp.bizzyco.ai`, sign in to Bizzy in the browser tab that opens, and approve the consent screen. See [Authentication](/mcp-server/authentication) for the full flow. ## Integration Guides Connect to Anthropic's Claude Desktop app Integrate with Cursor IDE Set up Windsurf with Cascade ## Next Steps See what tools are available Learn about MCP server authentication # Windsurf Source: https://docs.bizzyco.ai/mcp-server/integrations/windsurf Connect Bizzy to Windsurf using MCP This guide walks you through connecting the Bizzy MCP server to Windsurf, allowing Cascade (Windsurf's AI) to access your contacts, messages, and other business data. ## Prerequisites Before you begin, ensure you have: * [Windsurf](https://windsurf.com/) installed * A Bizzy account ## Connect Windsurf supports streamable-HTTP MCP servers and runs the OAuth 2.1 + PKCE handshake for you. 1. Add Bizzy to `~/.codeium/windsurf/mcp_config.json`: ```json theme={null} { "mcpServers": { "bizzy": { "serverUrl": "https://mcp.bizzyco.ai/mcp" } } } ``` Or, from Windsurf, open the Command Palette with `Cmd+Shift+P` (Mac) / `Ctrl+Shift+P` (Windows/Linux), run **Open Windsurf Settings**, navigate to **Cascade → Plugins**, and add Bizzy as a custom MCP plugin pointing at `https://mcp.bizzyco.ai/mcp` — Windsurf writes the same JSON. 2. Restart Windsurf. 3. The first time Cascade uses a Bizzy tool — or when you click **Connect** in the plugin entry — Windsurf opens a browser tab for OAuth. 4. Sign in to Bizzy and approve the consent screen. Cascade then has access to the tools you granted. See [Authentication](/mcp-server/authentication) for details on the OAuth handshake. ## Verification To verify the connection is working: 1. Open Cascade (Windsurf's AI assistant) 2. Ask: "What Bizzy tools do you have access to?" 3. Cascade should list the available tools ## Example Usage Once connected, you can use Bizzy tools in Cascade: | Task | Example Prompt | | --------------------- | ------------------------------------------------ | | Find contact info | "Look up contact information for our vendor" | | Search communications | "Find messages mentioning the deployment issue" | | View thread | "Show the full conversation thread with support" | ## Troubleshooting **Possible causes:** * Configuration file in wrong location * Invalid JSON syntax * Windsurf not restarted **Solutions:** 1. Verify the file is at `~/.codeium/windsurf/mcp_config.json` 2. Validate your JSON syntax 3. Completely restart Windsurf If the OAuth browser tab fails to load, check that you can reach `https://mcp.bizzyco.ai/.well-known/oauth-protected-resource` from your machine. If Cascade shows a stale token error, remove the `bizzy` entry from `~/.codeium/windsurf/mcp_config.json`, restart Windsurf, and re-add it — that forces a fresh Dynamic Client Registration. See [Authentication](/mcp-server/authentication) for the underlying flow. Cascade has a limit of 100 total tools. If you have many MCP servers configured, you may need to disable some tools. **Solution:** 1. Open **Windsurf Settings**, navigate to **Cascade → Plugins** 2. Navigate to the Tools tab 3. Toggle off tools you don't need ## Next Steps Explore all available MCP tools Learn about MCP server authentication # Introduction Source: https://docs.bizzyco.ai/mcp-server/introduction Connect AI agents to Bizzy using the Model Context Protocol The Bizzy MCP Server provides AI agents with direct access to your business communication platform. Using the Model Context Protocol (MCP), agents can manage contacts, customers, messages, automations, and more through a standardized interface. ## What is MCP? The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard that enables AI assistants to interact with external systems through a unified interface. Instead of building custom integrations for each AI platform, MCP provides a single connection point that works with Claude, GPT-based agents, and other MCP-compatible AI systems. MCP uses a client-server architecture where AI agents connect as clients to the Bizzy MCP server. The server exposes tools that agents can discover and invoke to perform actions on your behalf. ## Why Use Bizzy's MCP Server? * **Direct AI Access** - Give your AI agents the ability to read and manage your business data without building custom APIs * **Permission Control** - Fine-grained permissions let you control exactly what each agent can access * **Real-Time Operations** - Agents can create contacts, send messages, manage customers, and automate workflows in real-time * **Standardized Protocol** - Works with any MCP-compatible AI assistant or automation platform ## Available Tools The MCP server provides **106 tools** across 12 resource categories: | Category | Tools | Description | | ------------------- | ----- | ------------------------------------------------------------ | | **Automations** | 7 | Create, update, and inspect automations and their executions | | **Businesses** | 20 | Business profile, offerings, and online/physical presences | | **Contacts** | 20 | Contacts and their emails, phones, and addresses | | **Customers** | 10 | Customer records and customer transactions | | **Domains** | 15 | Domains, domain contacts, and domain registrations | | **Email Addresses** | 2 | List and read connected email addresses | | **Email Templates** | 7 | Manage templates, render previews, and send templated email | | **Files** | 5 | Upload, download, list, search, and delete files | | **Folders** | 2 | Create and list folders | | **Messages** | 6 | Read messages, threads, and attachments; update status | | **Phone Numbers** | 2 | List and read connected phone numbers | | **Tasks** | 10 | Task CRUD, search, and assignee management | Phone numbers are not yet generally available: the 2 tools in that category are advertised only to organizations with phone enabled. See [Phone Number Tools](/mcp-server/tools/phone-numbers). ## Use Cases ### AI Assistants Connect Claude Desktop or other AI assistants to Bizzy. Your assistant can then: * Look up contact information during conversations * Create follow-up tasks after meetings * Search through message history * Draft and queue messages for review ### Workflow Automation Build automated workflows that leverage AI decision-making: * Process incoming leads and create customer records * Categorize and route messages to appropriate team members * Generate reports from business data * Trigger automations based on AI analysis ### Custom Integrations Develop custom AI-powered applications that interact with Bizzy: * Build chatbots that can access customer information * Create AI agents that manage your inbox * Integrate with other business tools through AI orchestration ## Transports The MCP server supports two transports. Pick the one your client expects: * **Streamable HTTP** at `/mcp` — the current MCP transport; recommended for new clients. * **Server-Sent Events (SSE)** at `/sse` — kept for compatibility with clients that implement the earlier SSE transport. See the [Connection Guide](/mcp-server/connection) for full URLs and setup details. ## Next Steps Learn how MCP clients authenticate to the server Connect your AI agents to the MCP server # Automation Tools Source: https://docs.bizzyco.ai/mcp-server/tools/automations Create, manage, and inspect organization automations and their executions The Bizzy MCP server provides 7 tools for managing automations and inspecting their execution history. These tools are organized into two categories: automations and executions. ## Automations Core tools for creating, reading, updating, and deleting automations. ### createAutomation Create a new automation with trigger event, conditions, and instructions. **Permission:** `automations:write` **Parameters:** | Name | Type | Required | Description | | -------------- | ----------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | `name` | string | Yes | The name of the automation | | `description` | string | No | A description of what the automation does | | `triggerEvent` | string \| null | No | The event type that triggers this automation (e.g., "message", "contact", "customer") | | `condition` | `Record` | No | A key-value map of conditions that must be met for the automation to execute. Values must be strings or booleans (no nesting) | | `instructions` | string | Yes | Natural language instructions describing what the automation should do | | `createdBy` | string (UUID) | No | The user ID who created the automation | | `enabled` | boolean | No | Whether the automation is enabled (defaults to true) | After creation, the automation is generated and evaluated asynchronously. System-managed fields like generated code, evaluation results, group metadata, and execution counters are populated by the platform — do not pass them in here, as they are overwritten or ignored. **Returns:** The created automation object. *** ### getAutomation Get details of a specific automation by ID. **Permission:** `automations:read` **Parameters:** | Name | Type | Required | Description | | -------------- | ------------- | -------- | ------------------------------------ | | `automationId` | string (UUID) | Yes | The ID of the automation to retrieve | **Returns:** The automation object, or `null` if not found. *** ### listAutomations List automations with pagination. **Permission:** `automations:read` **Parameters:** | Name | Type | Required | Default | Description | | -------- | ------ | -------- | ------- | -------------------------------------------- | | `limit` | number | No | 20 | Number of automations to return (1-100) | | `offset` | number | No | 0 | Number of automations to skip for pagination | **Returns:** ```json theme={null} { "automations": [...], "count": 42, "limit": 20, "offset": 0 } ``` *** ### updateAutomation Update an existing automation - all fields are optional except `automationId`. **Permission:** `automations:write` **Parameters:** | Name | Type | Required | Description | | -------------- | ----------------------------------- | -------- | ---------------------------------------------------------------------- | | `automationId` | string (UUID) | Yes | The ID of the automation to update | | `name` | string | No | Update the automation name | | `description` | string | No | Update the description | | `triggerEvent` | string | No | Update the trigger event | | `condition` | `Record` | No | Update the conditions. Values must be strings or booleans (no nesting) | | `instructions` | string | No | Update the instructions | | `createdBy` | string (UUID) | No | Update the creator | | `enabled` | boolean | No | Enable or disable the automation | **Returns:** The updated automation object. *** ### deleteAutomation Delete an automation (soft delete). **Permission:** `automations:delete` **Parameters:** | Name | Type | Required | Description | | -------------- | ------------- | -------- | ---------------------------------- | | `automationId` | string (UUID) | Yes | The ID of the automation to delete | **Returns:** The deleted automation object. *** ## Executions Tools for inspecting individual automation executions and their history. ### getAutomationExecution Get details of a specific automation execution by ID. **Permission:** `automations.executions:read` **Parameters:** | Name | Type | Required | Description | | ------------- | ------------- | -------- | ---------------------------------------------- | | `executionId` | string (UUID) | Yes | The ID of the automation execution to retrieve | **Returns:** The automation execution object, or `null` if not found. *** ### listAutomationExecutions List automation executions with pagination, optionally filtered by automation ID. **Permission:** `automations.executions:read` **Parameters:** | Name | Type | Required | Default | Description | | -------------- | ------------- | -------- | ------- | ------------------------------------------- | | `automationId` | string (UUID) | No | - | Filter executions by automation ID | | `limit` | number | No | 20 | Number of executions to return (1-100) | | `offset` | number | No | 0 | Number of executions to skip for pagination | **Returns:** ```json theme={null} { "executions": [...], "count": 17, "limit": 20, "offset": 0 } ``` *** ## Next Steps Manage contacts and their associated data Learn how MCP clients authenticate to the server # Business Tools Source: https://docs.bizzyco.ai/mcp-server/tools/businesses Manage businesses, profiles, offerings, and online and physical presences The Bizzy MCP server provides 20 tools for managing businesses, their profile, offerings, and online and physical presences. These tools are organized into five categories: businesses, business profile, offerings, online presences, and physical presences. ## Businesses Core tools for reading and updating businesses. Businesses are provisioned with the organization, so there are no `create` or `delete` tools. ### getBusiness Get details for a specific business by ID. **Permission:** `businesses:read` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------- | -------- | ------------------------------ | | `businessId` | string (UUID) | Yes | ID of the business to retrieve | **Returns:** Business object, or `null` if not found. *** ### listBusinesses List all businesses in the organization. **Permission:** `businesses:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Maximum number of items to return (max: 100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "businesses": [...], "count": 3, "limit": 10, "offset": 0 } ``` *** ### updateBusiness Update an existing business by ID. **Permission:** `businesses:write` **Parameters:** | Name | Type | Required | Description | | ------ | ------------- | -------- | ---------------------------- | | `id` | string (UUID) | Yes | ID of the business to update | | `name` | string | No | The name of the business | Stripe Connect-related fields on the business record are managed by the Stripe integration — do not pass them in here, as they are overwritten or ignored. **Returns:** The updated business object. *** ## Business Profile Tools for reading and updating the descriptive profile of a business. The profile is created alongside the business, so there is no `create`, `list`, or `delete` tool — there is exactly one profile per business. ### getBusinessProfile Get the detailed profile of a business by ID. **Permission:** `businesses.profiles:read` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------- | -------- | ----------------------------------------------------------------------------- | | `businessId` | string (UUID) | Yes | ID of the business whose profile to retrieve (profile shares the business ID) | **Returns:** Business profile object, or `null` if not found. *** ### updateBusinessProfile Update the profile information of a business. **Permission:** `businesses.profiles:write` **Parameters:** | Name | Type | Required | Description | | ------------- | -------------------------------- | -------- | ------------------------------------------------------ | | `id` | string (UUID) | Yes | The ID of the business profile to update | | `description` | string \| null | No | A new detailed description of the business (optional) | | `industries` | string\[] \| null | No | New industries the business operates in (optional) | | `data` | Record\ \| null | No | Additional business data as key-value pairs (optional) | **Returns:** The updated business profile object. *** ## Offerings Tools for managing the products and services a business offers. ### createBusinessOffering Create a new product or service offering for a business. **Permission:** `businesses.offerings:write` **Parameters:** | Name | Type | Required | Description | | ------------- | --------------- | -------- | -------------------------------------------------------------- | | `businessId` | string (UUID) | Yes | The ID of the business this offering belongs to | | `name` | string | Yes | The name of the offering | | `description` | string \| null | No | A description of the offering (optional) | | `isService` | boolean \| null | No | Whether this is a service (true) or product (false) - optional | **Returns:** The created business offering object. *** ### getBusinessOffering Get details of a specific business offering by ID. **Permission:** `businesses.offerings:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the business offering to retrieve | **Returns:** Business offering object, or `null` if not found. *** ### listBusinessOfferings List all products and services offered by a business. **Permission:** `businesses.offerings:read` **Parameters:** | Name | Type | Required | Default | Description | | ------------ | ------------- | -------- | ------- | -------------------------------------------- | | `businessId` | string (UUID) | Yes | - | The ID of the business to list offerings for | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | **Returns:** ```json theme={null} { "offerings": [...], "count": 12, "limit": 100, "offset": 0 } ``` *** ### updateBusinessOffering Update details of an existing business offering. **Permission:** `businesses.offerings:write` **Parameters:** | Name | Type | Required | Description | | ------------- | --------------- | -------- | -------------------------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the business offering to update | | `name` | string | No | The new name for the offering (optional) | | `description` | string \| null | No | A new description for the offering (optional) | | `isService` | boolean \| null | No | Whether this is a service (true) or product (false) - optional | **Returns:** The updated business offering object. *** ### deleteBusinessOffering Delete a business offering (soft delete). **Permission:** `businesses.offerings:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ----------------------------------------- | | `id` | string (UUID) | Yes | The ID of the business offering to delete | **Returns:** The deleted business offering object. *** ## Online Presences Tools for managing a business's online presence — websites, social media profiles, marketplace listings, and similar. ### createBusinessOnlinePresence Create a new online presence for a business (website, social media, marketplace, etc.). **Permission:** `businesses.online-presences:write` **Parameters:** | Name | Type | Required | Description | | ------------- | -------------- | -------- | ---------------------------------------------------------------------------------------- | | `businessId` | string (UUID) | Yes | The ID of the business this online presence belongs to | | `name` | string | Yes | The name of the online presence (e.g., "Company Website", "Facebook Page") | | `url` | string \| null | No | The URL of the online presence (optional) | | `description` | string \| null | No | A description of the online presence (optional) | | `type` | string \| null | No | The type of online presence (e.g., "website", "social\_media", "marketplace") (optional) | | `provider` | string \| null | No | The provider or platform (e.g., "facebook", "linkedin", "amazon") (optional) | **Returns:** The created business online presence object. *** ### getBusinessOnlinePresence Get details of a specific business online presence by ID. **Permission:** `businesses.online-presences:read` **Parameters:** | Name | Type | Required | Description | | ------------------ | ------------- | -------- | -------------------------------------------------- | | `onlinePresenceId` | string (UUID) | Yes | The ID of the business online presence to retrieve | **Returns:** Business online presence object, or `null` if not found. *** ### listBusinessOnlinePresences List all online presences for a specific business. **Permission:** `businesses.online-presences:read` **Parameters:** | Name | Type | Required | Default | Description | | ------------ | ------------- | -------- | ------- | --------------------------------------------------- | | `businessId` | string (UUID) | Yes | - | The ID of the business to list online presences for | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | **Returns:** ```json theme={null} { "onlinePresences": [...], "count": 4, "limit": 100, "offset": 0 } ``` *** ### updateBusinessOnlinePresence Update an existing business online presence - all fields are optional except onlinePresenceId. **Permission:** `businesses.online-presences:write` **Parameters:** | Name | Type | Required | Description | | ------------------ | -------------- | -------- | ------------------------------------------------ | | `onlinePresenceId` | string (UUID) | Yes | The ID of the business online presence to update | | `name` | string | No | Update the online presence name | | `url` | string \| null | No | Update the URL | | `description` | string \| null | No | Update the description | | `type` | string \| null | No | Update the type of online presence | | `provider` | string \| null | No | Update the provider or platform | **Returns:** The updated business online presence object. *** ### deleteBusinessOnlinePresence Delete a business online presence (soft delete). **Permission:** `businesses.online-presences:delete` **Parameters:** | Name | Type | Required | Description | | ------------------ | ------------- | -------- | ------------------------------------------------ | | `onlinePresenceId` | string (UUID) | Yes | The ID of the business online presence to delete | **Returns:** The deleted business online presence object. *** ## Physical Presences Tools for managing a business's physical locations — offices, stores, warehouses, and similar. ### createBusinessPhysicalPresence Create a new physical location (office, store, warehouse, etc.) for a business. **Permission:** `businesses.physical-presences:write` **Parameters:** | Name | Type | Required | Description | | ------------- | -------------- | -------- | ------------------------------------------------------------------------- | | `businessId` | string (UUID) | Yes | The ID of the business this physical location belongs to | | `name` | string | Yes | The name of the physical location (e.g., "Main Office", "Downtown Store") | | `description` | string \| null | No | A description of the physical location (optional) | | `address` | string \| null | No | The full address of the physical location (optional) | **Returns:** The created business physical presence object. *** ### getBusinessPhysicalPresence Get details of a specific business physical location by ID. **Permission:** `businesses.physical-presences:read` **Parameters:** | Name | Type | Required | Description | | -------------------- | ------------- | -------- | ---------------------------------------------------- | | `physicalPresenceId` | string (UUID) | Yes | The ID of the business physical presence to retrieve | **Returns:** Business physical presence object, or `null` if not found. *** ### listBusinessPhysicalPresences List all physical locations (offices, stores, etc.) for a business. **Permission:** `businesses.physical-presences:read` **Parameters:** | Name | Type | Required | Default | Description | | ------------ | ------------- | -------- | ------- | ----------------------------------------------------- | | `businessId` | string (UUID) | Yes | - | The ID of the business to list physical locations for | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | **Returns:** ```json theme={null} { "physicalPresences": [...], "count": 2, "limit": 100, "offset": 0 } ``` *** ### updateBusinessPhysicalPresence Update an existing business physical location - all fields are optional except physicalPresenceId. **Permission:** `businesses.physical-presences:write` **Parameters:** | Name | Type | Required | Description | | -------------------- | -------------- | -------- | -------------------------------------------------- | | `physicalPresenceId` | string (UUID) | Yes | The ID of the business physical presence to update | | `name` | string | No | Update the physical location name | | `description` | string \| null | No | Update the description | | `address` | string \| null | No | Update the address | **Returns:** The updated business physical presence object. *** ### deleteBusinessPhysicalPresence Delete a business physical location (soft delete). **Permission:** `businesses.physical-presences:delete` **Parameters:** | Name | Type | Required | Description | | -------------------- | ------------- | -------- | -------------------------------------------------- | | `physicalPresenceId` | string (UUID) | Yes | The ID of the business physical presence to delete | **Returns:** The deleted business physical presence object. *** ## Next Steps Manage customers and their relationships with your business Learn how MCP clients authenticate to the server # Contact Tools Source: https://docs.bizzyco.ai/mcp-server/tools/contacts Manage contacts, emails, addresses, and phone numbers The Bizzy MCP server provides 21 tools for managing contacts and their associated data. These tools are organized into four categories: contact management, emails, addresses, and phone numbers. ## Contact Management Core tools for creating, reading, updating, and deleting contacts. ### createContact Create a new contact with name, email, phone, and company information. **Permission:** `contacts:write` **Parameters:** | Name | Type | Required | Description | | -------------- | --------- | -------- | ------------------------------------ | | `firstName` | string | No | The contact's first name | | `lastName` | string | No | The contact's last name | | `name` | string | No | Full display name | | `company` | string | No | Company or organization affiliation | | `jobTitle` | string | No | Job title or role | | `title` | string | No | Honorific or prefix (e.g., Mr, Dr) | | `picture` | string | No | URL to the contact's profile picture | | `notes` | string | No | Internal notes and comments | | `emails` | string\[] | No | Array of email addresses | | `phoneNumbers` | string\[] | No | Array of phone numbers | | `addresses` | object\[] | No | Array of address objects | **Address object:** | Name | Type | Required | Description | | ------------ | ------ | -------- | --------------------- | | `country` | string | Yes | Country | | `city` | string | Yes | City | | `label` | string | No | Label for the address | | `address1` | string | No | Address line 1 | | `address2` | string | No | Address line 2 | | `state` | string | No | State | | `postalCode` | string | No | Postal code | **Returns:** The created contact object with all associated data. *** ### getContact Get details of a specific contact by ID. **Permission:** `contacts:read` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | --------------------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact to retrieve | **Returns:** Contact object with all associated addresses, emails, and phone numbers. *** ### listContacts List contacts in the organization with pagination. **Permission:** `contacts:read` **Parameters:** | Name | Type | Required | Default | Description | | -------- | ------ | -------- | ------- | ----------------------------------------- | | `limit` | number | No | 50 | Number of contacts to return (1-100) | | `offset` | number | No | 0 | Number of contacts to skip for pagination | **Returns:** ```json theme={null} { "contacts": [...], "count": 150, "limit": 50, "offset": 0 } ``` *** ### updateContact Update an existing contact. **Permission:** `contacts:write` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | ------------------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact to update | | `firstName` | string | No | Update the contact's first name | | `lastName` | string | No | Update the contact's last name | | `name` | string | No | Update the full display name | | `company` | string | No | Update the company | | `jobTitle` | string | No | Update the job title | | `title` | string | No | Update the honorific | | `picture` | string | No | Update the profile picture URL | | `notes` | string | No | Update internal notes | **Returns:** The updated contact object. *** ### deleteContact Delete a contact (soft delete). **Permission:** `contacts:delete` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | ------------------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact to delete | **Returns:** The deleted contact object. *** ## Contact Emails Tools for managing email addresses associated with contacts. ### createContactEmail Create a new email address for a contact. **Permission:** `contacts.emails:write` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | -------------------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact | | `email` | string | Yes | The email address | | `label` | string | No | Label (e.g., "work", "personal") | **Returns:** The created contact email object. *** ### getContactEmail Get details of a specific contact email. **Permission:** `contacts.emails:read` **Parameters:** | Name | Type | Required | Description | | --------- | ------------- | -------- | ------------------------------- | | `emailId` | string (UUID) | Yes | The ID of the email to retrieve | **Returns:** Contact email object with all details. *** ### listContactEmails List all email addresses for a specific contact. **Permission:** `contacts.emails:read` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | --------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact | **Returns:** ```json theme={null} { "emails": [...], "count": 3 } ``` *** ### updateContactEmail Update an existing contact email address. **Permission:** `contacts.emails:write` **Parameters:** | Name | Type | Required | Description | | --------- | ------------- | -------- | ----------------------------- | | `emailId` | string (UUID) | Yes | The ID of the email to update | | `email` | string | No | Update the email address | | `label` | string | No | Update the label | **Returns:** The updated contact email object. *** ### deleteContactEmail Delete a contact email address. **Permission:** `contacts.emails:delete` **Parameters:** | Name | Type | Required | Description | | --------- | ------------- | -------- | ----------------------------- | | `emailId` | string (UUID) | Yes | The ID of the email to delete | **Returns:** The deleted contact email object. *** ## Contact Addresses Tools for managing physical addresses associated with contacts. ### createContactAddress Create a new address for a contact. **Permission:** `contacts.addresses:write` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------- | -------- | --------------------- | | `contactId` | string (UUID) | Yes | The ID of the contact | | `country` | string | Yes | Country | | `city` | string | Yes | City | | `label` | string | Yes | Label for the address | | `address1` | string | No | Address line 1 | | `address2` | string | No | Address line 2 | | `state` | string | No | State | | `postalCode` | string | No | Postal code | **Returns:** The created contact address object. *** ### getContactAddress Get details of a specific contact address. **Permission:** `contacts.addresses:read` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | --------------------------------- | | `addressId` | string (UUID) | Yes | The ID of the address to retrieve | **Returns:** Contact address object with all details. *** ### listContactAddresses List all addresses for a specific contact. **Permission:** `contacts.addresses:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | ---------------------------- | | `contactId` | string (UUID) | Yes | - | The ID of the contact | | `limit` | number | No | 10 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "asc" | Sort order ("asc" or "desc") | **Returns:** Array of contact address objects. *** ### updateContactAddress Update an existing contact address. **Permission:** `contacts.addresses:write` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------- | -------- | ------------------------------- | | `addressId` | string (UUID) | Yes | The ID of the address to update | | `country` | string | No | Update the country | | `city` | string | No | Update the city | | `label` | string | No | Update the label | | `address1` | string | No | Update address line 1 | | `address2` | string | No | Update address line 2 | | `state` | string | No | Update the state | | `postalCode` | string | No | Update the postal code | **Returns:** The updated contact address object. *** ### deleteContactAddress Delete a contact address. **Permission:** `contacts.addresses:delete` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | ------------------------------- | | `addressId` | string (UUID) | Yes | The ID of the address to delete | **Returns:** The deleted contact address object. *** ## Contact Phone Numbers Tools for managing phone numbers associated with contacts. ### createContactPhoneNumber Create a new phone number for a contact. **Permission:** `contacts.phoneNumbers:write` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | ------------------------------ | | `contactId` | string (UUID) | Yes | The ID of the contact | | `phoneNumber` | string | Yes | The phone number | | `countryCode` | string | Yes | Country code | | `nationalNumber` | string | Yes | National number | | `label` | string | Yes | Label (e.g., "mobile", "work") | **Returns:** The created contact phone number object. *** ### getContactPhoneNumber Get details of a specific contact phone number. **Permission:** `contacts.phoneNumbers:read` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | -------------------------------------- | | `phoneNumberId` | string (UUID) | Yes | The ID of the phone number to retrieve | **Returns:** Contact phone number object with all details. *** ### listContactPhoneNumbers List all phone numbers for a specific contact. **Permission:** `contacts.phoneNumbers:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | ---------------------------- | | `contactId` | string (UUID) | Yes | - | The ID of the contact | | `limit` | number | No | 10 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "asc" | Sort order ("asc" or "desc") | **Returns:** Array of contact phone number objects. *** ### updateContactPhoneNumber Update an existing contact phone number. **Permission:** `contacts.phoneNumbers:write` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | ------------------------------------ | | `phoneNumberId` | string (UUID) | Yes | The ID of the phone number to update | | `phoneNumber` | string | No | Update the phone number | | `countryCode` | string | No | Update the country code | | `nationalNumber` | string | No | Update the national number | | `label` | string | No | Update the label | **Returns:** The updated contact phone number object. *** ### deleteContactPhoneNumber Delete a contact phone number. **Permission:** `contacts.phoneNumbers:delete` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | ------------------------------------ | | `phoneNumberId` | string (UUID) | Yes | The ID of the phone number to delete | **Returns:** The deleted contact phone number object. *** ## Next Steps Manage messages and threads Learn how MCP clients authenticate to the server # Customer Tools Source: https://docs.bizzyco.ai/mcp-server/tools/customers Manage customers and their financial transactions The Bizzy MCP server provides 10 tools for managing customers and their transactions. These tools are organized into two categories: customers and customer transactions. ## Customers Core tools for creating, reading, updating, and deleting customer records. ### createCustomer Create a new customer record with business association and contact information. **Permission:** `customers:write` **Parameters:** | Name | Type | Required | Description | | --------------- | --------------------- | -------- | ------------------------------------------------------ | | `businessId` | string (UUID) | Yes | The ID of the business this customer belongs to | | `type` | string | Yes | Customer type (e.g., individual, business, enterprise) | | `contactId` | string (UUID) \| null | No | Optional reference to an existing contact record | | `name` | string \| null | No | Customer display name | | `email` | string \| null | No | Primary email address | | `phone` | string \| null | No | Primary phone number | | `notes` | string \| null | No | Internal notes and comments about the customer | | `status` | string \| null | No | Customer status (e.g., active, inactive, pending) | | `customerSince` | string \| null | No | Date when the customer relationship began (ISO 8601) | **Returns:** The created customer object. *** ### getCustomer Get a specific customer by ID. **Permission:** `customers:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ---------------------------------- | | `id` | string (UUID) | Yes | The ID of the customer to retrieve | **Returns:** Customer object, or `null` if not found. *** ### listCustomers List all customers for the organization with pagination. **Permission:** `customers:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Number of customers to return (1-100) | | `offset` | number | No | 0 | Number of customers to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "customers": [...], "count": 10, "limit": 10, "offset": 0 } ``` *** ### updateCustomer Update an existing customer record. **Permission:** `customers:write` **Parameters:** | Name | Type | Required | Description | | --------------- | --------------------- | -------- | ------------------------------------------------------ | | `id` | string (UUID) | Yes | The ID of the customer to update | | `businessId` | string (UUID) | No | The ID of the business this customer belongs to | | `contactId` | string (UUID) \| null | No | Reference to an existing contact record | | `type` | string | No | Customer type (e.g., individual, business, enterprise) | | `name` | string \| null | No | Customer display name | | `email` | string \| null | No | Primary email address | | `phone` | string \| null | No | Primary phone number | | `notes` | string \| null | No | Internal notes and comments about the customer | | `status` | string \| null | No | Customer status (e.g., active, inactive, pending) | | `customerSince` | string \| null | No | Date when the customer relationship began (ISO 8601) | **Returns:** The updated customer object. *** ### deleteCustomer Delete a customer (soft delete). **Permission:** `customers:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | -------------------------------- | | `id` | string (UUID) | Yes | The ID of the customer to delete | **Returns:** The deleted customer object. *** ## Customer Transactions Tools for recording and managing financial transactions associated with customers. ### createCustomerTransaction Create a new customer transaction to record a financial activity. **Permission:** `customers.transactions:write` **Parameters:** | Name | Type | Required | Description | | ----------------- | -------------- | -------- | ------------------------------------------------------------- | | `customerId` | string (UUID) | Yes | UUID of the customer this transaction belongs to | | `businessId` | string (UUID) | Yes | UUID of the business associated with the transaction | | `amount` | string | Yes | Transaction amount as a string (to handle decimal precision) | | `currency` | string | Yes | Currency code (e.g., USD, EUR) | | `status` | string | Yes | Transaction status (e.g., pending, completed, failed) | | `type` | string | Yes | Transaction type (e.g., purchase, refund, subscription) | | `description` | string \| null | No | Optional description of the transaction | | `transactionDate` | string \| null | No | Optional date when the transaction occurred (ISO 8601 format) | **Returns:** The created customer transaction object. *** ### getCustomerTransaction Get a specific customer transaction by its ID. **Permission:** `customers.transactions:read` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | -------------------------------------------- | | `transactionId` | string (UUID) | Yes | UUID of the customer transaction to retrieve | **Returns:** Customer transaction object, or `null` if not found. *** ### listCustomerTransactions List all transactions for a specific customer with pagination support. **Permission:** `customers.transactions:read` **Parameters:** | Name | Type | Required | Default | Description | | ------------ | ------------- | -------- | ------- | --------------------------------------------------- | | `customerId` | string (UUID) | Yes | - | UUID of the customer whose transactions to retrieve | | `limit` | number | No | 10 | Maximum number of items to return (1-100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "transactions": [...], "count": 25, "limit": 10, "offset": 0 } ``` *** ### updateCustomerTransaction Update an existing customer transaction - all fields are optional except `transactionId`. **Permission:** `customers.transactions:write` **Parameters:** | Name | Type | Required | Description | | ----------------- | -------------- | -------- | ----------------------------------------------------------------------- | | `transactionId` | string (UUID) | Yes | UUID of the customer transaction to update | | `businessId` | string (UUID) | No | Update the business associated with the transaction | | `amount` | string | No | Update the transaction amount as a string (to handle decimal precision) | | `currency` | string | No | Update the currency code (e.g., USD, EUR) | | `status` | string | No | Update the transaction status (e.g., pending, completed, failed) | | `type` | string | No | Update the transaction type (e.g., purchase, refund, subscription) | | `description` | string \| null | No | Update the description of the transaction | | `transactionDate` | string \| null | No | Update the date when the transaction occurred (ISO 8601 format) | **Returns:** The updated customer transaction object. *** ### deleteCustomerTransaction Delete a customer transaction (soft delete). **Permission:** `customers.transactions:delete` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | ------------------------------------------ | | `transactionId` | string (UUID) | Yes | UUID of the customer transaction to delete | **Returns:** The deleted customer transaction object. *** ## Next Steps Manage contacts that may be linked to customers Learn how MCP clients authenticate to the server # Domain Tools Source: https://docs.bizzyco.ai/mcp-server/tools/domains Manage domains, WHOIS contacts, and domain registrations The Bizzy MCP server provides 24 tools for managing domains and their associated registration data. These tools are organized into four categories: domains (including availability search, registration purchase, verification, and renewal), domain contacts, domain registrations, and DNS records. Domain Contacts on this page are the registrant, admin, and tech contacts attached to a domain registration (WHOIS data). They are distinct from CRM Contacts (people in your address book) — see [Contact Tools](/mcp-server/tools/contacts) for those. ## Domains Tools for managing domain records used for DNS and email. ### searchDomainAvailability Check whether one or more domains are available to register, with pricing. Provide a fully-qualified `domain`, or a `query` label paired with one or more `tlds`. This is read-only — it does not register a domain or charge anything. **Permission:** `domains:read` **Parameters:** | Name | Type | Required | Default | Description | | -------- | --------------- | -------- | ------- | ----------------------------------------------------------------------------------- | | `domain` | string | No\* | - | A fully-qualified domain to check (e.g. `example.com`) | | `query` | string | No\* | - | A second-level label, no TLD (e.g. `acme`), checked across `tlds` | | `tlds` | array of string | No | `[com]` | TLDs to pair with `query` (e.g. `["com", "io", "co"]`). Ignored unless `query` set. | \*Provide `domain`, or `query` (with optional `tlds`). A single call checks at most 25 names (`query` × `tlds` counts one name per TLD); larger fan-outs are rejected. **Returns:** An array of results, one per requested name. Each entry has a `status`: * `ok` — the name was checked. Includes `available`, `premium`, and prices (integer cents USD with the standard markup applied, or `null` when the registry returns no price). * `rate_limited` — the name could not be checked right now because the registrar rate limit was hit. The name was neither confirmed available nor taken — retry it shortly (`retryAfterMs`, when present, hints how long to wait) and do not treat it as registered. The rest of the batch is still returned, so retry only the affected names. ```json theme={null} [ { "status": "ok", "domain": "example.com", "available": true, "premium": false, "registrationPrice": 1200, "renewalPrice": 1200, "currency": "USD" }, { "status": "rate_limited", "domain": "example.io", "retryAfterMs": 800 } ] ``` *** ### registerDomain Purchase and register a domain for the organization. This is the real registration action — the same flow as `POST /v1/domain-registrations` in the REST API: it fetches a live quote, confirms availability with the registrar, charges the account default payment method off-session, and queues domain provisioning. This tool charges real money and a completed registration cannot be undone. Nothing is charged if the live quote exceeds `maxAmountCents`. In Bizzy agent chat, a human must approve each call before any charge. The MCP server has no approval flow, so this tool is only callable over MCP when the agent's `domain-registrations.purchase` write permission is explicitly set to **Allow** — at the default **Ask** level it is not exposed to MCP clients at all. The `purchase` sub-resource is scoped to this tool alone: allowing other domain-registration tools does not enable it, and the grant must be explicit — it is never inherited from a broader `domain-registrations` permission. **Permission:** `domain-registrations.purchase:write` (default level **Ask** — approval-gated in agent chat; over MCP, callable only at **Allow**) **Parameters:** | Name | Type | Required | Default | Description | | ---------------- | ------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `domain` | string | Yes | - | The fully-qualified domain to register (e.g. `acme.com`) | | `periodYears` | number | No | 1 | Initial registration period in years (1–10) | | `maxAmountCents` | number | Yes | - | Hard spend ceiling in USD cents; the call fails with `PRICE_EXCEEDS_MAXIMUM` (and charges nothing) if the quote is higher | | `autoRenew` | boolean | No | true | Whether the registration renews automatically each year | | `whoisPrivacy` | boolean | No | true | Whether WHOIS privacy protection is enabled | | `contact` | object | Yes | - | Registrant (WHOIS) contact: `firstName`, `lastName`, `address1`, `city`, `stateProvince`, `postalCode`, `country` (2-letter), `email`, `phone`, plus optional `label`, `address2`, `organizationName`, `jobTitle` (`jobTitle` is required when `organizationName` is set) | | `idempotencyKey` | string | Yes | - | Caller-controlled retry key. Generate a fresh UUID per distinct purchase attempt; reuse the exact same value when retrying — a reused key replays the original result instead of charging again | **Returns:** The queued provisioning operation: ```json theme={null} { "operationId": "9f8c2b1a-4d3e-4a6b-8c1d-2e3f4a5b6c7d", "status": "queued", "domain": "acme.com" } ``` Typed failures include `DOMAIN_UNAVAILABLE`, `PRICE_EXCEEDS_MAXIMUM`, `PAYMENT_METHOD_REQUIRED`, and `PAYMENT_FAILED`. If provisioning cannot be queued after a successful charge, the charge is automatically refunded (`DOMAIN_REGISTRATION_ENQUEUE_FAILED`) — retry with a new `idempotencyKey`. *** ### verifyDomain Start or check TXT ownership verification for an externally owned domain — the same flow as `POST /v1/domains/{id}/verification` and `POST /v1/domains/{id}/verification/check` in the REST API. If verification has not started (or previously failed or expired), a new verification token is issued, hourly background checking begins, and the TXT record to publish is returned. If verification is already pending, one live DNS check runs immediately instead. The tool is idempotent: a pending, unexpired token is never rotated and no duplicate background checking is started, so it is safe to call repeatedly to poll status. **Permission:** `domains:write` (default level **Ask** — approval-gated in agent chat; over MCP, callable only when the agent's `domains` write permission resolves to **Allow**) **Parameters:** | Name | Type | Required | Default | Description | | ---------- | ------------- | -------- | ------- | ------------------------------- | | `domainId` | string (UUID) | Yes | - | The ID of the domain to verify. | **Returns:** The verification state plus the TXT record to publish: ```json theme={null} { "status": "pending", "initiated": true, "recordName": "_bizzy.example.com", "expectedValue": "bizzy-domain-verification=3f2a…", "attempts": 0, "verifiedAt": null, "expiresAt": "2026-07-11T00:00:00.000Z", "reason": "Publish the TXT record; verification is checked hourly." } ``` `status` is `verified`, `pending`, or `failed`; `initiated` is `true` only when this call issued a fresh token (publish `recordName`/`expectedValue` as a DNS TXT record at the domain's DNS host). Verification expires after 7 days — calling the tool again after expiry issues a new token. *** ### getDomainRenewalPrice Preview the live renewal price for a registered domain, without charging anything — the same quote as `GET /v1/domains/{id}/registration/renewal-price` in the REST API, and the exact amount `renewDomain` will enforce its `maxAmountCents` ceiling against. This is read-only. **Permission:** `domains:read` **Parameters:** | Name | Type | Required | Default | Description | | ------------- | ------------- | -------- | ------- | ----------------------------------------- | | `domainId` | string (UUID) | Yes | - | The ID of the registered domain to price. | | `periodYears` | number | No | 1 | Renewal period in years (1–10). | **Returns:** The live renewal quote in integer USD cents (standard markup applied): ```json theme={null} { "domain": "acme.com", "periodYears": 1, "amountCents": 1800, "currency": "usd", "premium": false } ``` Fails with `DOMAIN_NOT_REGISTERED` for verified-only domains and `DOMAIN_PRICE_UNAVAILABLE` when the registrar cannot return a live price. *** ### renewDomain Renew a registered domain for the organization. This is the real renewal action — the same flow as `POST /v1/domains/{id}/registration/renew` in the REST API: it checks the live price against your ceiling, queues a renewal operation, and the renewal workflow charges the account default payment method off-session, renews the domain at the registrar, and extends the expiration date. This tool charges real money. Nothing is charged if the live price exceeds `maxAmountCents`; if the registrar renewal fails after the charge, the charge is automatically refunded. In Bizzy agent chat, a human must approve each call before any charge. The MCP server has no approval flow, so this tool is only callable over MCP when the agent's `domain-registrations.renewal` write permission is explicitly set to **Allow** — at the default **Ask** level it is not exposed to MCP clients at all. The `renewal` sub-resource is scoped to this tool alone: allowing other domain-registration tools does not enable it, and the grant must be explicit — it is never inherited from a broader `domain-registrations` permission. **Permission:** `domain-registrations.renewal:write` (default level **Ask** — approval-gated in agent chat; over MCP, callable only at **Allow**) **Parameters:** | Name | Type | Required | Default | Description | | ---------------- | ------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `domainId` | string (UUID) | Yes | - | The ID of the registered domain to renew | | `periodYears` | number | No | 1 | Renewal period in years (1–10) | | `maxAmountCents` | number | Yes | - | Hard spend ceiling in USD cents; the call fails with `PRICE_EXCEEDS_MAXIMUM` (and charges nothing) if the live price is higher | | `idempotencyKey` | string | Yes | - | Caller-controlled retry key. Generate a fresh UUID per distinct renewal attempt; reuse the exact same value (and the original `periodYears`/`maxAmountCents`) when retrying — a reused key replays the original result instead of renewing again; mismatched parameters are rejected | **Returns:** The queued renewal operation, with the pre-flight quote (`amountCents` is `null` when the call replayed an existing operation): ```json theme={null} { "operationId": "9f8c2b1a-4d3e-4a6b-8c1d-2e3f4a5b6c7d", "status": "queued", "domain": "acme.com", "amountCents": 1800 } ``` Typed failures include `DOMAIN_NOT_REGISTERED`, `PRICE_EXCEEDS_MAXIMUM`, and `DOMAIN_RENEWAL_ENQUEUE_FAILED` (nothing was charged — retry with a new `idempotencyKey`). *** ### createDomain Create a new domain record for DNS and email management. **Permission:** `domains:write` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | --------------------- | -------- | --------- | ----------------------------------------------- | | `domain` | string | Yes | - | The domain name (e.g., example.com) | | `status` | string | No | "pending" | Domain status (e.g., active, pending, inactive) | | `zoneId` | string \| null | No | - | Optional DNS zone ID for the domain | | `createdBy` | string (UUID) \| null | No | - | Optional user ID who created the domain | Verification, registrar, and Resend-related fields are managed by the platform — do not pass them in here, as they are overwritten or ignored. **Returns:** The created domain object. *** ### getDomain Get a specific domain by ID. **Permission:** `domains:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | -------------------------------- | | `id` | string (UUID) | Yes | The ID of the domain to retrieve | **Returns:** Domain object, or `null` if not found. *** ### listDomains List all domains for the organization with pagination. **Permission:** `domains:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Maximum number of items to return (max: 100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "domains": [...], "count": 12, "limit": 10, "offset": 0 } ``` *** ### updateDomain Update an existing domain record. **Permission:** `domains:write` **Parameters:** | Name | Type | Required | Description | | ----------- | --------------------- | -------- | ----------------------------------- | | `id` | string (UUID) | Yes | The ID of the domain to update | | `domain` | string | No | The domain name (e.g., example.com) | | `createdBy` | string (UUID) \| null | No | User ID who created the domain | Lifecycle and registration fields — `status`, `source`, `zoneId`, and `expiresAt` — are not writable through this tool; they are managed by Bizzy (expiry sweeps, renewals, registrar events, and zone provisioning). **Returns:** The updated domain object. *** ### deleteDomain Delete a domain (soft delete). Verified (externally registered) domains can be deleted at any time; their DNS records at the external DNS host are left untouched. Registered (Bizzy-managed) domains can only be deleted once their registration has expired **and** their DNS zone holds no records beyond the zone's built-in ones (the apex NS set and SOA) — disable email for the domain first so Bizzy removes the email records it manages, then delete any remaining records with the DNS record tools. A renewal that is already queued or running also blocks the deletion until it finishes. A blocked deletion fails with `REGISTERED_DOMAIN_NOT_EXPIRED`, `REGISTERED_DOMAIN_RENEWAL_IN_FLIGHT`, or `REGISTERED_DOMAIN_DNS_NOT_EMPTY`; the last names the blocking records. If the domain had email enabled, Bizzy also retires its email configuration — revoking the sending credential and removing the domain from the email provider. That cleanup is best-effort: if the provider is unreachable, the deletion still goes through and any credential Bizzy could not revoke is recorded rather than lost track of. **Permission:** `domains:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ------------------------------ | | `id` | string (UUID) | Yes | The ID of the domain to delete | **Returns:** The deleted domain object. *** ## Domain Contacts Tools for managing the registration contacts used as the registrant on domains registered through Bizzy. These are WHOIS-style contacts held at the domain registrar — not CRM contacts. Contacts are organization-wide: the same contact can be the registrant for any number of domains. Writes go through to the registrar, so what these tools change is also what appears in the public WHOIS record. `externalId` and `accountId` identify the contact at the registrar and are assigned when it is created. They are returned on the contact object and cannot be supplied or changed by a caller. When one of these tools refuses a request, it comes back the way every MCP tool result does — as a text block describing what happened, not a status code or an error object. The refusal messages are quoted below so you know what to look for. ### createDomainContact Create a registration contact at the domain registrar and store it. Usable as the registrant when registering a domain. **Permission:** `domain-contacts:write` **Parameters:** | Name | Type | Required | Description | | ------------------ | ------------- | -------- | ------------------------------------------------------------------------------------------------ | | `domainId` | string (UUID) | No | Domain this contact is for. Decides which registrar holds it; defaults to the platform registrar | | `label` | string | No | Label for your own organization. Never sent to the registrar | | `firstName` | string | Yes | First name of the contact | | `lastName` | string | Yes | Last name of the contact | | `organizationName` | string | No | Organization/company name | | `jobTitle` | string | No | Job title. Required when `organizationName` is set | | `address1` | string | Yes | Primary address line | | `address2` | string | No | Secondary address line | | `city` | string | Yes | City | | `stateProvince` | string | Yes | State or province | | `postalCode` | string | Yes | Postal/ZIP code | | `country` | string | Yes | ISO-3166 alpha-2 country code (e.g., US, CA) | | `email` | string | Yes | Contact email address | | `phone` | string | Yes | Contact phone number in E.164 format | The address fields are required even though they are nullable on the stored record: the registry rejects an incomplete registrant. **Returns:** The created domain contact object, carrying the registrar-assigned `externalId` and `accountId`. *** ### getDomainContact Get a specific domain contact by ID. **Permission:** `domain-contacts:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ---------------------------------------- | | `id` | string (UUID) | Yes | The ID of the domain contact to retrieve | **Returns:** Domain contact object, or `null` if not found. *** ### listDomainContacts List all domain contacts for the organization with pagination. **Permission:** `domain-contacts:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Maximum number of items to return (max: 100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "domainContacts": [...], "count": 8, "limit": 10, "offset": 0 } ``` *** ### updateDomainContact Update a registration contact at the domain registrar and in Bizzy. **Permission:** `domain-contacts:write` Changing `firstName`, `lastName`, `organizationName`, or `email` restarts ICANN's 15-day registrant email verification on **every** domain using this contact as its registrant. Address and phone changes do not. See [Registration Contacts](/user-guide/domains/contacts). **Parameters:** | Name | Type | Required | Description | | ------------------ | -------------- | -------- | ------------------------------------------------------------ | | `id` | string (UUID) | Yes | The ID of the domain contact to update | | `label` | string | No | Label for your own organization. Never sent to the registrar | | `firstName` | string | No | First name of the contact | | `lastName` | string | No | Last name of the contact | | `organizationName` | string \| null | No | Organization/company name | | `jobTitle` | string \| null | No | Job title. Required when `organizationName` is set | | `address1` | string | No | Primary address line | | `address2` | string \| null | No | Secondary address line | | `city` | string | No | City | | `stateProvince` | string | No | State or province | | `postalCode` | string | No | Postal/ZIP code | | `country` | string | No | ISO-3166 alpha-2 country code (e.g., US, CA) | | `email` | string | No | Contact email address | | `phone` | string | No | Contact phone number in E.164 format | A `label`-only change is local and never reaches the registrar, so it is allowed even on a contact whose registration details are fixed. Some contacts cannot have their registration details changed after registration. Attempting it fails with the text `Error: This operation (registrant contact updates) is not available` — create a new contact instead. **Returns:** The updated domain contact object. *** ### deleteDomainContact Remove a registration contact from Bizzy and from the domain registrar. **Permission:** `domain-contacts:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | -------------------------------------- | | `id` | string (UUID) | Yes | The ID of the domain contact to delete | Refused while the contact is still the registrant of a live domain. The call fails with the text `Error: This contact is the registrant for example.com and cannot be removed`, naming every domain that is using it. Point those domains at a different registrant first. **Returns:** The deleted domain contact object. *** ## Domain Registrations Tools for managing domain registration records that track ownership, renewal, and registrar metadata. ### createDomainRegistration Create a new domain registration record to track domain ownership and renewal. **Permission:** `domain-registrations:write` **Parameters:** | Name | Type | Required | Description | | ------------------ | --------------------- | -------- | ------------------------------------------------------- | | `state` | string | Yes | Registration state (e.g., registered, pending, expired) | | `externalDomainId` | string | Yes | External domain ID from the registrar | | `externalId` | string | Yes | External registration ID from the registrar | | `autoRenew` | boolean | Yes | Whether auto-renewal is enabled | | `whoisPrivacy` | boolean | Yes | Whether WHOIS privacy is enabled | | `transferLock` | boolean | Yes | Whether domain transfer lock is enabled | | `period` | number | Yes | Registration period in years | | `domainId` | string (UUID) \| null | No | Optional reference to the related domain record | | `createdBy` | string (UUID) \| null | No | Optional user ID who created the registration | **Returns:** The created domain registration object. *** ### getDomainRegistration Get a specific domain registration by ID. **Permission:** `domain-registrations:read` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | --------------------------------------------- | | `registrationId` | string (UUID) | Yes | The ID of the domain registration to retrieve | **Returns:** Domain registration object, or `null` if not found. *** ### listDomainRegistrations List all domain registrations for the organization with pagination. **Permission:** `domain-registrations:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Maximum number of items to return (max: 100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "domainRegistrations": [...], "count": 5, "limit": 10, "offset": 0 } ``` *** ### updateDomainRegistration Update an existing domain registration record - all fields are optional except registrationId. **Permission:** `domain-registrations:write` **Parameters:** | Name | Type | Required | Description | | ------------------ | --------------------- | -------- | ------------------------------------------------------------------ | | `registrationId` | string (UUID) | Yes | The ID of the domain registration to update | | `state` | string | No | Update the registration state (e.g., registered, pending, expired) | | `externalDomainId` | string | No | Update the external domain ID from the registrar | | `externalId` | string | No | Update the external registration ID from the registrar | | `autoRenew` | boolean | No | Update whether auto-renewal is enabled | | `whoisPrivacy` | boolean | No | Update whether WHOIS privacy is enabled | | `transferLock` | boolean | No | Update whether domain transfer lock is enabled | | `period` | number | No | Update the registration period in years | | `createdBy` | string (UUID) \| null | No | Update the user ID who created the registration | **Returns:** The updated domain registration object. *** ### deleteDomainRegistration Delete a domain registration (soft delete). **Permission:** `domain-registrations:delete` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | ------------------------------------------- | | `registrationId` | string (UUID) | Yes | The ID of the domain registration to delete | **Returns:** The deleted domain registration object. *** ## Domain DNS Records Tools for managing a registered domain's DNS records. DNS is backed by Cloudflare (the customer DNS account is the system of record — records are not stored in Bizzy). These tools only work for domains **registered through Bizzy**; the DNS zone is created automatically the first time a record is added. ### listDnsRecords List the DNS records for a registered domain. Returns an empty list if the domain has no DNS zone yet. **Permission:** `domains:read` **Parameters:** | Name | Type | Required | Description | | ---------- | ------------- | -------- | ------------------------------------ | | `domainId` | string (UUID) | Yes | The domain whose DNS records to list | **Returns:** ```json theme={null} { "dnsRecords": [...], "count": 4 } ``` *** ### createDnsRecord Create a DNS record for a registered domain. **Permission:** `domains:write` **Parameters:** | Name | Type | Required | Default | Description | | ---------- | ------------- | -------- | ------- | ------------------------------------------------------------ | | `domainId` | string (UUID) | Yes | - | The domain to add the DNS record to | | `type` | string | Yes | - | Record type: A, AAAA, CNAME, MX, TXT, SRV, CAA, or NS | | `name` | string | Yes | - | Record name (use `@` for the root domain) | | `content` | string | Yes | - | Record value (e.g. an IP address or target hostname) | | `ttl` | number | No | 3600 | Time-to-live in seconds (60–86400) | | `proxied` | boolean | No | - | Whether traffic is proxied through Cloudflare (A/AAAA/CNAME) | | `priority` | number | No | - | Priority (required for MX and SRV records) | **Returns:** The created DNS record object. *** ### updateDnsRecord Update a DNS record. This is a full replacement — provide all record fields. **Permission:** `domains:write` **Parameters:** | Name | Type | Required | Default | Description | | ---------- | ------------- | -------- | ------- | ------------------------------------------------------------ | | `domainId` | string (UUID) | Yes | - | The domain the DNS record belongs to | | `recordId` | string | Yes | - | The DNS record ID to update | | `type` | string | Yes | - | Record type: A, AAAA, CNAME, MX, TXT, SRV, CAA, or NS | | `name` | string | Yes | - | Record name (use `@` for the root domain) | | `content` | string | Yes | - | Record value (e.g. an IP address or target hostname) | | `ttl` | number | No | 3600 | Time-to-live in seconds (60–86400) | | `proxied` | boolean | No | - | Whether traffic is proxied through Cloudflare (A/AAAA/CNAME) | | `priority` | number | No | - | Priority (required for MX and SRV records) | **Returns:** The updated DNS record object. *** ### deleteDnsRecord Delete a DNS record from a registered domain. **Permission:** `domains:write` **Parameters:** | Name | Type | Required | Description | | ---------- | ------------- | -------- | ------------------------------------ | | `domainId` | string (UUID) | Yes | The domain the DNS record belongs to | | `recordId` | string | Yes | The DNS record ID to delete | **Returns:** `{ "success": true, "recordId": "..." }` *** ## Next Steps Manage CRM contacts, distinct from the WHOIS-style domain contacts above Learn how MCP clients authenticate to the server # Email Address Tools Source: https://docs.bizzyco.ai/mcp-server/tools/email-addresses Inspect organization email addresses available for sending and receiving The Bizzy MCP server provides 2 tools for inspecting the email addresses connected to your organization. Use these tools to discover which addresses are available for sending templated emails or to look up a specific address by ID. ## getEmailAddress Get details of a specific email address by ID. **Permission:** `email-addresses:read` **Parameters:** | Name | Type | Required | Description | | ---------------- | ------------- | -------- | --------------------------------------- | | `emailAddressId` | string (UUID) | Yes | The ID of the email address to retrieve | **Returns:** The email address object, or `null` if not found. *** ## listEmailAddresses List email addresses for the organization with optional filtering. **Permission:** `email-addresses:read` **Parameters:** | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | --------------------------------------------------------------------------------------------------- | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | | `provider` | string | No | - | Filter by email provider. Valid values: `google`, `microsoft`, `bizzy`, `apple` | | `status` | string | No | - | Filter by email address status. Valid values: `pending`, `active`, `disabled`, `errored`, `deleted` | **Returns:** ```json theme={null} { "emailAddresses": [...], "count": 12, "limit": 100, "offset": 0 } ``` *** ## Next Steps Create, render, and send templated emails Learn how MCP clients authenticate to the server # Email Template Tools Source: https://docs.bizzyco.ai/mcp-server/tools/email-templates Create, render, and send Mustache-based email templates The Bizzy MCP server provides 7 tools for managing email templates and using them to send templated emails. These tools are organized into two categories: templates and render & send. ## Templates CRUD tools for managing reusable email templates. Templates support Mustache syntax for dynamic content in both subject lines and bodies. ### createEmailTemplate Create a new email template with name (max 200 chars), subject (max 1000 chars), body (max 50000 chars), and optional variables. Templates support Mustache syntax for dynamic content. **Permission:** `emailTemplates:write` **Parameters:** | Name | Type | Required | Description | | ------------- | --------- | -------- | ----------------------------------------------------------------------------------------- | | `name` | string | Yes | The name of the email template (1-200 characters) | | `subject` | string | Yes | The subject line of the email template (1-1000 characters). Supports Mustache variables. | | `body` | string | Yes | The body content of the email template (1-50000 characters). Supports Mustache variables. | | `description` | string | No | Optional description of the email template (max 2000 characters) | | `variables` | string\[] | No | Optional list of variable names used in the template for documentation | **Returns:** The created email template object. *** ### getEmailTemplate Get a specific email template by ID, including all template details. **Permission:** `emailTemplates:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ---------------------------------------- | | `id` | string (UUID) | Yes | The ID of the email template to retrieve | **Returns:** The email template object, or `null` if not found. *** ### listEmailTemplates List email templates for the organization with pagination. Supports filtering by status and name. **Permission:** `emailTemplates:read` **Parameters:** | Name | Type | Required | Default | Description | | -------- | ------ | -------- | ------- | ------------------------------------------------------------------- | | `limit` | number | No | 10 | Number of email templates to return (1-100) | | `offset` | number | No | 0 | Number of email templates to skip for pagination | | `status` | string | No | - | Filter by template status (`active` or `archived`) | | `name` | string | No | - | Filter by name (case-insensitive partial match, max 200 characters) | **Returns:** ```json theme={null} { "emailTemplates": [...], "count": 8, "limit": 10, "offset": 0 } ``` *** ### updateEmailTemplate Update an existing email template with new values for any template fields. Name max 200 chars, subject max 1000 chars, body max 50000 chars. **Permission:** `emailTemplates:write` **Parameters:** | Name | Type | Required | Description | | ------------- | ----------------- | -------- | ------------------------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the email template to update | | `name` | string | No | The name of the email template (1-200 characters) | | `description` | string \| null | No | Description of the email template (max 2000 characters) | | `subject` | string | No | The subject line of the email template (1-1000 characters) | | `body` | string | No | The body content of the email template (1-50000 characters) | | `variables` | string\[] \| null | No | List of variable names used in the template for documentation | | `status` | string | No | Template status (`active` or `archived`) | **Returns:** The updated email template object. *** ### deleteEmailTemplate Delete an email template (soft delete). **Permission:** `emailTemplates:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | -------------------------------------- | | `id` | string (UUID) | Yes | The ID of the email template to delete | **Returns:** The deleted email template object. *** ## Render & Send Tools for rendering templates with variable data and dispatching templated emails through the organization's email pipeline. ### renderEmailTemplate Render an email template by ID with provided data variables using Mustache templating. Returns the rendered subject and the raw rendered body — the delivered email (see `sendTemplatedEmail`) additionally sanitizes the body (unsafe markup removed) and wraps it in a standard email layout. **Permission:** `emailTemplates:read` **Parameters:** | Name | Type | Required | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------ | | `templateId` | string (UUID) | Yes | The ID of the email template to render | | `data` | Record\ | Yes | Key-value pairs of variable data to render into the template | **Returns:** Object with `subject` and `body` strings containing the rendered content. *** ### sendTemplatedEmail Render an email template with data and send it. Fetches the template, renders subject and body with the provided data, sanitizes the body (scripts, event handlers, and other unsafe markup are removed), wraps it in a standard email-client-compatible layout, auto-generates a plain-text alternative, and sends the email from the specified email address. **Permission:** `emailTemplates:write` **Parameters:** | Name | Type | Required | Description | | -------------------- | ------------------------ | -------- | ------------------------------------------------- | | `templateId` | string (UUID) | Yes | The ID of the email template to use | | `data` | Record\ | Yes | Template variable data for rendering | | `to` | string\[] | Yes | Array of recipient email addresses (at least one) | | `fromEmailAddressId` | string (UUID) | Yes | The ID of the email address to send from | | `cc` | string\[] | No | Array of CC email addresses | | `bcc` | string\[] | No | Array of BCC email addresses | | `replyTo` | string | No | Reply-to email address | **Returns:** Object with `subject`, `to`, `from`, `rendered`, and `sent` fields summarizing the send result. *** ## Next Steps Discover which email addresses are available to send from Learn how MCP clients authenticate to the server # File Tools Source: https://docs.bizzyco.ai/mcp-server/tools/files Upload, download, search, and organize files in organization storage The Bizzy MCP server provides 8 tools for managing files and folders in organization storage. These tools are organized into two categories: files and folders. ## Files Tools for uploading, downloading, listing, searching, and deleting files. File content is exchanged as base64-encoded strings to support the MCP protocol. ### uploadFile Upload a file to organization storage with base64-encoded content. **Permission:** `files:write` **Parameters:** | Name | Type | Required | Description | | ------------- | --------------------- | -------- | ------------------------------------------------------------ | | `filename` | string | Yes | Name of the file (1-255 characters) | | `content` | string | Yes | Base64-encoded file content (max 10MB file size) | | `contentType` | string | Yes | MIME type of the file (e.g., `application/pdf`, `image/png`) | | `folderId` | string (UUID) \| null | No | Optional folder ID to place the file in | | `description` | string | No | Optional description of the file (max 5000 characters) | | `tags` | string\[] | No | Optional tags for the file (max 10) | **Returns:** Object with `success` boolean and a `file` object containing `id`, `filename`, `size`, `contentType`, and `folderId`. *** ### downloadFile Download a file from organization storage as base64-encoded content. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | ------------------------------ | | `fileId` | string (UUID) | Yes | The ID of the file to download | **Returns:** Object with a `file` metadata object (`id`, `filename`, `contentType`, `size`) and a `content` string containing base64-encoded file bytes. Downloads are gated by each file's `agentAccessEnabled` flag. Files with agent access disabled return an error. *** ### listFiles List files in organization storage with optional folder filtering and pagination. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | --------------------- | -------- | ------- | --------------------------------------------------------------- | | `folderId` | string (UUID) \| null | No | - | Filter by folder ID (`null` for root level, omit for all files) | | `limit` | number | No | 10 | Number of files to return (1-100) | | `offset` | number | No | 0 | Pagination offset | | `sortOrder` | string | No | "desc" | Sort order by creation date (`asc` or `desc`) | **Returns:** ```json theme={null} { "files": [...], "count": 23, "limit": 10, "offset": 0 } ``` *** ### searchFiles Find files by name **or content**. `searchFiles` runs a hybrid full-text search that combines two signals and fuses them so a file matching on both ranks highest: * **Metadata** — filename, description, and tags. * **Content** — the text of the file's indexed pages (for files Bizzy has finished indexing). Returns ranked **file records** (not passages). Use `searchFiles` to locate files; use [`askFiles`](#askfiles) to answer a question from their contents. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | --------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | - | Search query matched against filename, description, tags, and file content (1-255 characters) | | `limit` | number | No | 10 | Number of results to return (1-100) | | `offset` | number | No | 0 | Pagination offset | | `folderIds` | string\[] | No | - | Optional list of folder UUIDs to restrict the search to. When provided, only files inside the listed folders match — files at the root level (no folder) are excluded | **Returns:** ```json theme={null} { "files": [...], "count": 5, "query": "invoice", "limit": 10, "offset": 0 } ``` Results are limited to files with agent access enabled. A file excluded from content indexing still appears when its **name** matches — exclusion only removes it from content matching, not from search. `count` reflects the deduplicated union of metadata and content candidates within a bounded window (up to 500 matches per side), not an exhaustive tally. For large result sets, page through with `limit` and `offset`. *** ### askFiles New Answer a natural-language question using passages retrieved from the organization's indexed files. Returns ranked **citations** — each backed by a source file, page number (when available), and an excerpt — rather than whole file records. Use this when a question may be answered by uploaded documents, and always cite the returned files when synthesizing an answer. **Permission:** `files:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | --------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | - | Natural-language question to answer from file contents (1-1000 chars) | | `limit` | number | No | 10 | Maximum number of citations to return (1-50) | | `folderIds` | string\[] | No | - | Optional list of folder UUIDs to restrict retrieval to. When provided, only files inside the listed folders match — files at the root level (no folder) are excluded | **Returns:** Object with the echoed `query` and a `citations` array. Each citation contains `fileId`, `filename`, `pageNumber` (nullable), `snippet`, `score`, and `chunkIndex`. ```json theme={null} { "query": "What is the roofing warranty term?", "citations": [ { "fileId": "f4c1…", "filename": "warranty.pdf", "pageNumber": 3, "snippet": "Roofing warranty covers material defects for 25 years…", "score": 0.0328, "chunkIndex": 7 } ] } ``` Only files with agent access enabled and a completed indexing status are searched. Newly uploaded files become answerable once indexing finishes. *** ### deleteFile Delete a file from organization storage (soft delete). **Permission:** `files:delete` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | ---------------------------- | | `fileId` | string (UUID) | Yes | The ID of the file to delete | **Returns:** Object with `success` boolean, the deleted `file` object, and a `message` string. *** ## Folders Tools for organizing files into a folder hierarchy. Folders can be nested up to 5 levels deep. ### createFolder Create a new folder in organization storage with optional parent folder (max 5 levels deep). **Permission:** `folders:write` **Parameters:** | Name | Type | Required | Description | | ---------------- | --------------------- | -------- | ------------------------------------------------- | | `name` | string | Yes | Name of the folder (1-255 characters) | | `parentFolderId` | string (UUID) \| null | No | Optional parent folder ID (`null` for root level) | **Returns:** The created folder object. *** ### listFolders List folders in organization storage with optional parent folder filtering and pagination. **Permission:** `folders:read` **Parameters:** | Name | Type | Required | Default | Description | | ---------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------------ | | `parentFolderId` | string (UUID) \| null | No | - | Filter by parent folder ID (`null` for root level, omit for all folders) | | `limit` | number | No | 10 | Number of folders to return (1-100) | | `offset` | number | No | 0 | Pagination offset | | `sortOrder` | string | No | "desc" | Sort order by creation date (`asc` or `desc`) | **Returns:** ```json theme={null} { "folders": [...], "count": 6, "limit": 10, "offset": 0 } ``` *** ## Next Steps Manage contacts and their associated data Learn how MCP clients authenticate to the server # Tools Overview Source: https://docs.bizzyco.ai/mcp-server/tools/index Available tools in the Bizzy MCP Server The Bizzy MCP server provides tools for managing your business communications and contacts. Tools are organized by resource type and require appropriate [permissions](/mcp-server/authentication) to access. ## Available Tool Categories The MCP server exposes 116 tools across 11 resource categories. Each category has a dedicated reference page listing every tool, its parameters, permission, and return shape. | Category | Tools | Description | | ---------------------------------------------------- | ----- | --------------------------------------------------------------------- | | [Automations](/mcp-server/tools/automations) | 7 | Create, update, and inspect automations and their executions | | [Businesses](/mcp-server/tools/businesses) | 20 | Business profile, offerings, and online/physical presences | | [Contacts](/mcp-server/tools/contacts) | 20 | Contacts and their emails, phones, and addresses | | [Customers](/mcp-server/tools/customers) | 10 | Customer records and customer transactions | | [Domains](/mcp-server/tools/domains) | 24 | Domains, DNS records, search, registration, verification, and renewal | | [Email Addresses](/mcp-server/tools/email-addresses) | 2 | List and read connected email addresses | | [Email Templates](/mcp-server/tools/email-templates) | 7 | Manage templates, render previews, and send templated email | | [Files](/mcp-server/tools/files) | 8 | Upload, download, search, and delete files; manage folders | | [Messages](/mcp-server/tools/messages) | 6 | Read messages, threads, and attachments; update status | | [Phone Numbers](/mcp-server/tools/phone-numbers) | 2 | List and read connected phone numbers (only when phone is enabled) | | [Tasks](/mcp-server/tools/tasks) | 10 | Task CRUD, search, and assignee management | Phone numbers are not yet generally available, so the 2 tools in that category are advertised only to organizations with phone enabled. Every other category is always available. The contact phone-number tools under [Contacts](/mcp-server/tools/contacts) are unaffected. ## Permission Model Each tool requires specific permissions to execute. Permissions follow the pattern `resource:action` (e.g., `contacts:read`) or `resource.subresource:action` for nested resources (e.g., `contacts.emails:write`). **Permission levels:** | Action | Description | | -------- | --------------------------- | | `read` | View and list resources | | `write` | Create and update resources | | `delete` | Remove resources | **Examples:** * `contacts:read` - List and view contacts * `contacts:write` - Create and update contacts * `contacts.emails:write` - Add or update contact email addresses * `messages:read` - View and search messages You grant these permissions on the MCP server's consent screen during the OAuth handshake. The set of tools advertised over `tools/list` is filtered against the categories you approve. See [Authentication](/mcp-server/authentication) for the full flow. ## Common Starting Points 20 tools for managing contacts, emails, addresses, and phone numbers 6 tools for accessing messages, threads, and attachments 10 tools for managing tasks and assignees 8 tools for uploading, downloading, and organizing files ## Next Steps Learn how MCP clients authenticate to the server Connect to AI tools like Claude, Cursor, and Windsurf # Message Tools Source: https://docs.bizzyco.ai/mcp-server/tools/messages Access and manage messages, threads, and attachments The Bizzy MCP server provides 7 tools for accessing and managing messages. These tools allow you to retrieve messages, search content, manage message status, and view conversation threads. ## getMessage Get detailed information about a specific message by its ID, including all message type-specific fields (email headers, SMS encoding, WhatsApp media, etc.). **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Description | | ----------- | ------------- | -------- | ----------------------------- | | `messageId` | string (UUID) | Yes | ID of the message to retrieve | **Returns:** Message object with all type-specific fields. *** ## listMessages List messages in the organization with optional filtering. **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ------------------------------------------------------ | | `limit` | number | No | 10 | Maximum number of messages to return (1-100) | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | | `direction` | string | No | - | Filter by message direction ("incoming" or "outgoing") | **Returns:** Array of message objects. *** ## updateMessageStatus Update the status of a message - mark as read/unread, archive/unarchive, or snooze/unsnooze. **Permission:** `messages:write` **Parameters:** | Name | Type | Required | Description | | -------------- | -------------- | -------- | --------------------------------------------------------- | | `messageId` | string (UUID) | Yes | ID of the message to update | | `readAt` | string \| null | No | ISO datetime to mark as read, or `null` to mark as unread | | `archivedAt` | string \| null | No | ISO datetime to archive, or `null` to unarchive | | `snoozedUntil` | string \| null | No | ISO datetime to snooze until, or `null` to unsnooze | **Returns:** The updated message object. This tool only allows updating status fields for security reasons. To modify message content, use the appropriate channel-specific tools. *** ## getMessagesByContact Get all messages sent to or received from a specific contact. Useful for viewing the complete communication history with a contact. **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | ------------------------------------------------------------------------ | | `contactId` | string (UUID) | Yes | - | Contact ID to retrieve messages for | | `limit` | number | No | 20 | Maximum number of messages to return (1-100) | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | | `direction` | string | No | - | Filter by direction ("incoming" = from contact, "outgoing" = to contact) | **Returns:** Array of message objects from/to the specified contact. *** ## getMessageThread Get all messages that belong to the same conversation thread. Useful for viewing the complete conversation history. **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | ------------------------------------------------------------------------------ | | `threadId` | string | Yes | - | Thread ID to retrieve messages for | | `limit` | number | No | 50 | Maximum number of messages to return (1-100) | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "asc" | Sort order ("asc" = oldest first for conversation flow, "desc" = newest first) | | `direction` | string | No | - | Filter by message direction ("incoming" or "outgoing") | **Returns:** Array of message objects in the thread. *** ## listMessageAttachments List all file attachments associated with a specific message, including details like filename, size, content type, and URL. **Permission:** `messages:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | --------------------------------------------- | | `messageId` | string (UUID) | Yes | - | ID of the message | | `limit` | number | No | 20 | Maximum number of attachments to return | | `offset` | number | No | 0 | Offset for pagination | | `sortOrder` | string | No | "asc" | Sort order by creation date ("asc" or "desc") | **Returns:** Array of attachment objects with metadata (filename, size, content type, URL). *** ## Next Steps Manage contacts and their data Learn how MCP clients authenticate to the server # Phone Number Tools Source: https://docs.bizzyco.ai/mcp-server/tools/phone-numbers Inspect organization phone numbers used for SMS and voice channels The Bizzy MCP server provides 2 tools for inspecting the phone numbers connected to your organization. Use these tools to discover which numbers are available or to look up a specific number by ID. Phone numbers are not yet generally available. These two tools are only advertised over `tools/list` when phone is enabled for your organization — if you don't see them, they aren't part of your server's tool set, and calling them by name will fail. Contact support to have phone enabled. The contact phone-number tools on the [Contact Tools](/mcp-server/tools/contacts) page are unaffected and always available. ## getPhoneNumber Get details of a specific phone number by ID. **Permission:** `phone-numbers:read` **Parameters:** | Name | Type | Required | Description | | --------------- | ------------- | -------- | -------------------------------------- | | `phoneNumberId` | string (UUID) | Yes | The ID of the phone number to retrieve | **Returns:** The phone number object, or `null` if not found. *** ## listPhoneNumbers List phone numbers for the organization with optional filtering. **Permission:** `phone-numbers:read` **Parameters:** | Name | Type | Required | Default | Description | | ---------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------- | | `limit` | number | No | 100 | Maximum number of results | | `offset` | number | No | 0 | Offset for pagination | | `provider` | string | No | - | Filter by phone provider. Valid values: `telnyx`, `twilio` | | `status` | string | No | - | Filter by phone number status. Valid values: `pending`, `active`, `disabled`, `errored`, `deleted` | **Returns:** ```json theme={null} { "phoneNumbers": [...], "count": 4, "limit": 100, "offset": 0 } ``` *** ## Next Steps Inspect email addresses available for sending Learn how MCP clients authenticate to the server # Task Tools Source: https://docs.bizzyco.ai/mcp-server/tools/tasks Manage tasks, search them, and assign them to users The Bizzy MCP server provides 10 tools for managing tasks and their assignees. These tools are organized into two categories: tasks and assignees. ## Tasks Core tools for creating, reading, updating, deleting, and searching tasks. ### createTask Create a new task with title (max 500 chars), description (max 10,000 chars), priority settings, and optional metadata. Tasks can be categorized and assigned due dates. **Permission:** `tasks:write` **Parameters:** | Name | Type | Required | Default | Description | | ------------- | ---------------------------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------- | | `title` | string | Yes | - | The title of the task (1-500 characters) | | `description` | string | Yes | - | Detailed description of the task and what needs to be done | | `status` | string | No | "todo" | Current status of the task. Valid values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `cancelled` | | `category` | string \| null | No | - | Task category. Valid values: `bug_fix`, `feature_request`, `documentation`, `meeting`, `planning`, `research`, `review`, `other` | | `importance` | string \| null | No | - | How important this task is. Valid values: `low`, `medium`, `high` | | `urgency` | string \| null | No | - | How urgent this task is. Valid values: `low`, `medium`, `high` | | `dueDate` | string \| null | No | - | Due date for the task (ISO 8601 datetime with offset) | | `messageId` | string (UUID) \| null | No | - | Optional reference to a related message | | `contactId` | string (UUID) \| null | No | - | Optional reference to a related contact | | `metadata` | Record\ \| null | No | - | Additional structured metadata for the task | **Returns:** The created task object. *** ### getTask Get a specific task by ID, including all task details and assignees. **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ------------------------------ | | `id` | string (UUID) | Yes | The ID of the task to retrieve | **Returns:** Full task object with assignees, or `null` if not found. *** ### listTasks List all tasks for the organization with pagination, including assignee details. **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | --------------------------------------------- | | `limit` | number | No | 10 | Number of tasks to return (1-100) | | `offset` | number | No | 0 | Number of tasks to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "tasks": [...], "count": 42, "limit": 10, "offset": 0 } ``` *** ### updateTask Update an existing task with new values for any task fields. Title max 500 chars, description max 10,000 chars. **Permission:** `tasks:write` **Parameters:** | Name | Type | Required | Description | | ------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | | `id` | string (UUID) | Yes | The ID of the task to update | | `title` | string | No | The title of the task (1-500 characters) | | `description` | string | No | Detailed description of the task and what needs to be done | | `category` | string \| null | No | Task category. Valid values: `bug_fix`, `feature_request`, `documentation`, `meeting`, `planning`, `research`, `review`, `other` | | `importance` | string \| null | No | How important this task is. Valid values: `low`, `medium`, `high` | | `urgency` | string \| null | No | How urgent this task is. Valid values: `low`, `medium`, `high` | | `status` | string | No | Current status of the task. Valid values: `backlog`, `todo`, `in_progress`, `in_review`, `done`, `cancelled` | | `dueDate` | string \| null | No | Due date for the task (ISO 8601 datetime with offset) | | `messageId` | string (UUID) \| null | No | Reference to a related message | | `contactId` | string (UUID) \| null | No | Reference to a related contact | | `metadata` | Record\ \| null | No | Additional structured metadata for the task | **Returns:** The updated task object. *** ### deleteTask Delete a task (soft delete). **Permission:** `tasks:delete` **Parameters:** | Name | Type | Required | Description | | ---- | ------------- | -------- | ---------------------------- | | `id` | string (UUID) | Yes | The ID of the task to delete | **Returns:** The deleted task object. *** ### searchTasks Search for tasks using full-text search across title, description, and metadata. Supports automatic word stemming, phrase matching, and relevance ranking. Results are sorted by relevance (most relevant first). **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------ | -------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | string | Yes | - | Search query to find tasks using full-text search. Searches across title, description, and metadata. Supports automatic word stemming (e.g., "running" matches "run") and phrase matching (max 255 characters) | | `limit` | number | No | 10 | Maximum number of results to return (1-50) | | `offset` | number | No | 0 | Number of tasks to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by relevance rank ("desc" = most relevant first, "asc" = least relevant first) | **Returns:** Array of full task objects ordered by relevance. *** ## Assignees Tools for assigning users to tasks and listing assignment relationships. ### assignTask Assign a user to a task. **Permission:** `tasks:write` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | ---------------------------------------- | | `taskId` | string (UUID) | Yes | The ID of the task to assign | | `userId` | string (UUID) | Yes | The ID of the user to assign to the task | **Returns:** The created task assignee object. *** ### unassignTask Remove a user assignment from a task. **Permission:** `tasks:write` **Parameters:** | Name | Type | Required | Description | | -------- | ------------- | -------- | -------------------------------------------- | | `taskId` | string (UUID) | Yes | The ID of the task to unassign from | | `userId` | string (UUID) | Yes | The ID of the user to unassign from the task | **Returns:** The removed task assignee object. *** ### listTaskAssignees Get all users assigned to a specific task. **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | --------------------------------------------- | | `taskId` | string (UUID) | Yes | - | The ID of the task to get assignees for | | `limit` | number | No | 10 | Maximum number of items to return (1-100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "assignees": [...], "count": 3, "limit": 10, "offset": 0 } ``` *** ### listUserTasks Get all tasks assigned to a specific user. **Permission:** `tasks:read` **Parameters:** | Name | Type | Required | Default | Description | | ----------- | ------------- | -------- | ------- | ---------------------------------------------- | | `userId` | string (UUID) | Yes | - | The ID of the user to get task assignments for | | `limit` | number | No | 10 | Maximum number of items to return (1-100) | | `offset` | number | No | 0 | Number of items to skip for pagination | | `sortOrder` | string | No | "desc" | Sort order by creation date ("asc" or "desc") | **Returns:** ```json theme={null} { "assignments": [...], "count": 8, "limit": 10, "offset": 0 } ``` *** ## Next Steps Build automations that create or update tasks in response to events Learn how MCP clients authenticate to the server # Agent Conversations Source: https://docs.bizzyco.ai/user-guide/agent-conversations/index Browse past agent chats, filter by status, and resume any conversation Beta Every chat with an agent is saved. The **Agent Conversations** page lists every conversation across every agent in your organization — with filters for status and pagination for large histories. Agent conversations list ## The list view Columns typically include: * **Title** — auto-generated from the first message; editable on the detail page * **Agent** — which agent handled the conversation * **Status** — current state * **Last updated** — when the most recent message landed ### Status values | Status | Meaning | | ----------- | ----------------------------------- | | `active` | Open — you can still send messages | | `completed` | Ended cleanly | | `timeout` | The conversation ended on a timeout | | `error` | An error stopped the conversation | ### Filters * **Status** — pick one of the four statuses to narrow the list. * **Pagination** — page size defaults to 20 (max 100). ## Opening a conversation Click any row to open its [transcript](/user-guide/agent-conversations/transcripts), where you can see every message, every tool call, and every approval decision. ## Next steps Detailed conversation view Configure the agents that drive these conversations # Conversation Transcripts Source: https://docs.bizzyco.ai/user-guide/agent-conversations/transcripts Review the full message and tool-call history of a Bizzy agent conversation The conversation detail page shows every turn, every tool call, and every approval decision in the chat — in order. Conversation transcript view ## What you see ### Messages Each user and agent message renders as a bubble with the content and a timestamp. ### Tool invocations When the agent called a tool, you see an inline card with: * **Tool name** and **category** * **Inputs** — the arguments the agent passed (collapsed by default; click to expand) * **Outputs** — what the tool returned * **Duration** — how long the call took ### Tool approval audit For any tool set to **Ask**, the card also records: * Who approved or denied * The timestamp of the decision This gives you a complete trail of what the agent wanted to do and how you responded. ## Actions on the detail page | Action | How | Effect | | ---------- | ---------------------- | ----------------------------------------------------------------------------------- | | **Rename** | Edit the title | Updates the title via `PATCH` — useful when the auto-generated title isn't helpful | | **Delete** | Delete button | Soft-deletes the conversation — the transcript is hidden but recoverable by support | | **Resume** | Type into the composer | Sends a new message; if status was `active`, the conversation continues | ## When can I resume? * **Active:** always — just type and send. * **Completed / timeout / error:** sending a message reopens the conversation and changes its status back to active. Tool state may be stale (for example, if the conversation referenced a contact that has since been deleted). ## Exporting No UI export today. If you need a transcript out of Bizzy, contact support. ## Next steps Adjust what gets auto-approved Start a new conversation # Chatting with an Agent Source: https://docs.bizzyco.ai/user-guide/agents/chat The full-page Bizzy agent chat interface Each agent has a chat interface at `/{org}/agents/{id}` — a full-page, message-by-message view with inline tool calls and approval cards. Agent chat page with tool approval card ## Starting a conversation 1. Open an agent from the **Agents** list. 2. Type a message in the composer at the bottom of the chat. 3. Send. The agent thinks, optionally calls tools (subject to your [permissions](/user-guide/agents/tool-permissions)), and replies. ## Tool calls inline When the agent calls a tool, you see an inline card showing the tool name, inputs (collapsed by default — expand to see), and outputs once the call returns. If the tool is set to **Ask**, the card pauses with: * The tool's risk badge * The inputs the agent wants to use * **Approve** / **Deny** buttons The approval waits as long as you need — there's no countdown. The agent can't continue that conversation until you respond: **Approve** resumes it right where it paused, and **Deny** lets it explain and move on. A pending approval is tied to its own conversation, so starting a new chat leaves it parked — return to that conversation to approve or deny it. ## Files and images in chat When the agent or one of its tools produces a file, it appears in the conversation as an attachment card instead of raw text. Images show a thumbnail preview; other file types show a type icon with the filename and format. Use the download button on the card to save the file. Attachments in chat are display-only for now — you can't yet upload your own files from the composer. ## Multiple conversations Each conversation is independent, so you can keep several going at once — they run simultaneously without interfering with one another. Starting a new chat opens a fresh conversation; the one you were in keeps its full history and any work in progress. ## Resuming past conversations Past conversations appear in [Agent Conversations](/user-guide/agent-conversations/index). Open any conversation's detail page to see the full history; send a new message to continue from where it left off. ## Under the hood * The chat uses a WebSocket connection for low-latency streaming. * The UI is lazy-loaded, so the first open of an agent chat may take a moment. * Messages persist even if you close the tab — reload and you'll see what was already there. * Messages are grouped by day with a date separator (**Today**, **Yesterday**, or the date) so longer conversations are easy to scan. ## Troubleshooting | Problem | Likely cause | Fix | | -------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------ | | Agent just says "Max steps reached" | The agent hit its `maxSteps` budget mid-turn | Raise `maxSteps` on the agent, or simplify the request | | Tool keeps asking for approval | Permission set to **Ask** | Change to **Allow** in the Tools tab if you trust it | | Agent refuses a task it should be able to do | System prompt too restrictive, or tool set to **Deny** | Review the prompt and Tools tab | ## Next steps Review or resume past chats Fine-tune what the agent can do # Creating an Agent Source: https://docs.bizzyco.ai/user-guide/agents/creating Configure a new Bizzy agent with a system prompt, model, and LLM parameters 1. Go to **Agents** in the sidebar. 2. Click **New Agent**. 3. Fill in the form. Create agent form ## Required fields | Field | Notes | | ---------- | ----------------------------------------------------------------------- | | **Name** | Short label — shown in chat and conversation history | | **Type** | `Assistant` (general-purpose) or `Specialist` (narrower, task-focused) | | **Status** | `Active` to enable chat; `Disabled` to park it | | **Model** | See [Models](/user-guide/agents/models). Defaults to Claude Sonnet 4.6. | The type influences the default system prompt applied if you leave the prompt empty. ## System prompt Open the **System Prompt** section to customize behavior. Write in plain English — describe the agent's role, tone, any rules, and what kind of output you want. If left blank, a sensible default per type is used. The system prompt is the single biggest lever on agent behavior. Be specific about scope ("only answer support questions about our product X") and boundaries ("do not send email without explicit user confirmation"). ## LLM settings Advanced settings in the accordion — safe to leave at defaults for most cases: | Setting | Typical range | What it does | | --------------------- | ------------------- | ---------------------------------------------------- | | **Temperature** | 0 – 2 | Randomness. Lower = more deterministic | | **Max tokens** | Varies by model | Cap on output length per turn | | **Top P** | 0 – 1 | Nucleus sampling cutoff | | **Top K** | Integer | Candidate token cap | | **Frequency penalty** | -2 – 2 | Discourages repetition | | **Presence penalty** | -2 – 2 | Encourages new topics | | **Max steps** | Integer (default 5) | How many tool-call cycles the agent can run per turn | | **Max retries** | Integer | Retries on provider errors | ## Saving Click **Save**. The agent is created immediately. Tool permissions default to the regular-user baseline — open the new agent's detail page and visit the **Tools** tab to adjust. See [Tool Permissions](/user-guide/agents/tool-permissions). ## Default agent Each organization can have one **default agent**, marked with a badge in the list. The default agent is what Bizzy suggests when you haven't picked another one explicitly. To mark an agent as default, toggle the flag on its detail page. ## Next steps Available models and how to choose Decide what the agent can do # Agents Source: https://docs.bizzyco.ai/user-guide/agents/index Create interactive AI assistants with custom system prompts, tool permissions, and model selection Beta Agents are interactive AI assistants you can chat with inside Bizzy. Each agent has its own system prompt, model, and per-tool permissions, so you can make an agent that answers support email one way and a research agent that behaves entirely differently. Agents list ## Agents vs. Automations **Agents** are interactive — you open a chat window and talk to them, and they can ask for your approval before running tools. **[Automations](/user-guide/automations/index)** are event-triggered — they fire automatically on events like "new email received" without a human in the loop. The two complement each other: automations handle recurring, well-defined work; agents handle ad-hoc, exploratory work. ## What you can do Name, type, system prompt, model, LLM settings Claude, GPT, and Gemini models Allow / ask / deny each tool Full-page chat with tool approval Conversations with an agent are saved and visible in [Agent Conversations](/user-guide/agent-conversations/index), including the full tool-call history. # Agent Models Source: https://docs.bizzyco.ai/user-guide/agents/models LLM models available for Bizzy agents Each agent runs on an LLM you choose. Bizzy offers a curated set of models from multiple providers, so you can match each agent's model to the reasoning depth, speed, and cost its job calls for. ## Available models | Model | Typical use | | ----------------------------- | -------------------------------------------------------------- | | **Claude Sonnet** *(default)* | Balanced reasoning + cost for most agent tasks | | **Claude Haiku** | Fast, cheap — great for simple classification or short replies | | **Claude Opus** | Hardest reasoning, highest cost | | **GPT-4o** | Strong general model with broad tool use | | **GPT-4o Mini** | Smaller GPT-4o for cost-sensitive work | | **Gemini Flash** | Low-latency model | | **Gemini Pro** | Higher-capability Gemini model | No tier gating today — every organization can select any of these models. Usage is billed by the token, converted into Bizzy credits. See [Admin Guide → Billing](/admin-guide/billing/index) for how credits work. ## Picking a model Rough guidance: * **Default to Claude Sonnet.** It hits the best balance of quality and cost for most agent workloads. * **Move to Haiku or Flash** if latency and per-call cost matter more than reasoning depth (for example, a classifier agent that only picks a label). * **Move to Opus** only when a task consistently fails at Sonnet — the cost delta is substantial. ## Changing the model Open the agent's detail page and edit the **Model** field. The change applies to all new conversations; conversations already in progress continue on whichever model they started. ## Next steps Control what the agent can do The chat UI # Tool Permissions Source: https://docs.bizzyco.ai/user-guide/agents/tool-permissions Allow, ask, or deny each tool an agent can call Agents can use Bizzy tools — things like "read contact," "send email," "create task." You control what each agent is allowed to do on a per-tool basis. Tool permissions tab ## The three permission levels Each tool on each agent is set to one of three values: | Level | Icon | Behavior | | --------- | ------------- | ------------------------------------------------------ | | **Allow** | Green check | Agent calls the tool silently — no interruption | | **Ask** | Blue question | Agent pauses and requests your approval before calling | | **Deny** | Red X | Tool is hidden from the agent entirely | The "Ask" approval appears inline in the chat with a risk-level badge, and you can expand the card to see the exact tool input before approving. A pending approval waits as long as you need — there's no countdown or auto-deny — and the agent can't continue that conversation until you allow or deny it (only one approval is pending at a time). Allowing resumes the agent right where it paused; denying lets it explain and carry on. Starting a new chat cancels a pending approval. ## Finding the permissions UI 1. Open the agent's detail page. 2. Go to the **Tools** tab. 3. Tools are grouped by category (for example, Contacts, Messages, Tasks). Expand a category to see its tools, each with a three-way button. ## How defaults work When you create an agent, it inherits the **regular-user** baseline permissions for the organization. Tools considered sensitive default to **Ask**; lower-risk tools default to **Allow**. Your overrides are stored sparsely — only the tools where you deviate from the default are persisted. If the default shifts later (for example, we promote a new tool from risky to routine), agents inherit the new default unless you had explicitly overridden that tool. ## Risk levels Tool approval cards display a risk badge (low / medium / high) to help you decide quickly. Use your judgment: a low-risk tool misused is rarely damaging, a high-risk tool might send email from your domain or spend money. Changing permissions takes effect on the **next** tool call by the agent. A tool call already mid-flight when you change the setting will complete under the old rules. ## Next steps See approvals in action Review past approvals and denials # Creating Your First Automation Source: https://docs.bizzyco.ai/user-guide/automations/first-automation Build an AI-powered automation workflow in Bizzy This guide walks you through creating your first automation in Bizzy. By the end, you'll have a working automation that responds to events with AI-powered actions. For background on how automations work and what they can do, see [Automations Concepts](/get-started/concepts/automations). ## Prerequisites * A Bizzy account with an active organization * At least one connected email account * User permissions to create automations ## Step 1: Navigate to Automations 1. Click **Automations** in the sidebar navigation 2. View your existing automations (if any) 3. Click **Create Automation** or **New Automation** Create automation form ## Step 2: Name Your Automation Give your automation a clear, descriptive name: * **Good**: "Support Email Auto-Acknowledgment" * **Good**: "New Lead Welcome Message" * **Avoid**: "Automation 1" or "Test" The name helps you identify the automation later and understand its purpose at a glance. Automation names must be unique within your organization and under 100 characters. ## Step 3: Define the Trigger Event Specify what event should trigger this automation: ### Common Trigger Events | Event | When It Fires | | ------------------ | ------------------------------------------- | | New email received | An incoming email arrives in your inbox | | Contact created | A new contact is added to your organization | | Message sent | An outgoing email is sent | Enter a description of your trigger event. Be specific about when you want the automation to run. **Example triggers:** * "When a new email arrives from a domain ending in .edu" * "When a contact is created without a company name" * "When an email subject contains 'urgent' or 'help'" You can have several automations on the same trigger. When that event fires, **every** enabled automation matching it runs independently — so you can keep each one focused on a single job (for example, one to send an acknowledgment and another to tag the contact) instead of combining everything into one. ## Step 4: Write Your Instructions This is where you tell the AI what to do when the trigger fires. Write in natural language as if you were instructing a colleague. Be specific about the action, tone, and any conditions. Here's an example for a support auto-reply: ``` When a support email arrives: 1. Send an acknowledgment reply 2. Thank them for contacting support 3. Mention we typically respond within 24 hours 4. If they mention "urgent", add that we'll prioritize their request 5. Keep the tone friendly and professional 6. Keep the reply under 100 words ``` Instructions have a 5,000 character limit. If you need more complex logic, consider splitting into multiple automations. ## Step 5: Save and Enable Once you've configured your automation: 1. Review your settings 2. Click **Save** or **Create** to save the automation 3. The automation is enabled by default and starts running immediately ## Testing Your Automation After creating your automation: 1. **Trigger a test event** - Send yourself an email or perform the trigger action 2. **Check the results** - Verify the automation performed as expected 3. **Adjust if needed** - Edit the instructions to refine the behavior ## Managing Automations ### Viewing Automations All your automations are listed on the Automations page, showing: * Automation name * Trigger event * Status (enabled/disabled) * Last run time ### Enabling/Disabling Toggle an automation on or off: 1. Navigate to **Automations** 2. Find the automation 3. Click the enable/disable toggle Disabled automations don't run but retain their configuration. ### Editing Automations To modify an existing automation: 1. Click on the automation name 2. Update the fields as needed 3. Save your changes Changes take effect immediately for enabled automations. ### Deleting Automations To remove an automation: 1. Open the automation 2. Click **Delete** 3. Confirm the deletion Deleted automations cannot be recovered. Consider disabling instead if you might need it later. ## Example: Complete Automation Walkthrough Let's create a complete automation for acknowledging support emails: ### Configuration | Field | Value | | ----------------- | ----------------------------------------------------------------------- | | **Name** | Support Email Auto-Acknowledgment | | **Trigger Event** | New email received to [support@company.com](mailto:support@company.com) | | **Instructions** | See below | ### Instructions ``` When a new email arrives at the support address: 1. Send an immediate acknowledgment reply 2. Include these elements: - Thank them for contacting our support team - Confirm we received their message - Set expectations: we respond within 24 hours (Mon-Fri) - For urgent issues, mention they can call our hotline 3. Tone guidelines: - Professional but warm - Empathetic if they describe a problem - Concise - keep under 100 words 4. Sign off with: - "Best regards" - "The Bizzy Support Team" ``` ### Expected Result When someone emails [support@company.com](mailto:support@company.com), they'll receive a reply like: > Thank you for contacting Bizzy Support! We've received your message and a > member of our team will respond within 24 business hours. > > If your issue is urgent, you can reach our priority support line at > 1-800-XXX-XXXX. > > Best regards, The Bizzy Support Team ## Troubleshooting ### Automation Not Triggering | Issue | Cause | Solution | | ----------------- | ------------------------ | --------------------------------------- | | No action taken | Automation disabled | Check and enable the automation | | Wrong events | Trigger too specific | Broaden the trigger event description | | Permission denied | Insufficient permissions | Contact your admin to check permissions | ### Unexpected Results | Issue | Cause | Solution | | ------------------- | -------------------- | ---------------------------- | | Wrong tone | Instructions unclear | Add explicit tone guidelines | | Missing information | Context not provided | Add context to instructions | | Too verbose | No length guidance | Add word or sentence limits | ## Next Steps Connect more email accounts Organize contacts for automations # Automations Source: https://docs.bizzyco.ai/user-guide/automations/index Set up automated workflows in Bizzy Automations let you create AI-powered workflows that respond to events automatically. For background on how automations work, see [Automations Concepts](/get-started/concepts/automations). ## Getting Started Step-by-step guide to building an automation Build a complete AI-powered support workflow from scratch ## Common Use Cases | Scenario | Trigger | Action | | ------------------- | -------------------------- | ------------------------- | | Auto-acknowledgment | New email received | Send confirmation reply | | Lead qualification | Contact form submission | Categorize and route lead | | Support triage | Support email | Tag by urgency and type | | Meeting scheduling | Email with meeting request | Propose available times | ## Loop protection Bizzy automatically stops automations from running away in a loop, so a misconfigured automation can't burn through your usage unchecked. * **An automation never re-triggers on its own actions.** If an automation updates a customer and is also set to run when a customer is updated, its own update won't start it again. * **Deeply chained automations are stopped.** When one automation triggers another, which triggers another, Bizzy stops the chain once it nests too deep and **pauses** the automation that ran last. You'll get a notification (in-app and by email) telling you which automation was paused. A paused automation stays off until you turn it back on. Before re-enabling it, adjust its trigger or actions so it doesn't set itself off again — otherwise it will be paused again the next time the loop is detected. You can manage the notification under **Settings → Notifications → Automations**. # AI Suggestions Source: https://docs.bizzyco.ai/user-guide/businesses/ai-suggestions Let Bizzy draft your business profile, offerings, and presences Every section of the Business page has a **Suggest** button that uses an LLM to draft content based on what you've already filled in. It's the fastest way to go from an empty profile to a useful one. AI suggestions review modal ## How suggestions work 1. Click **Suggest** on any block (Name, Description, Industries, Offerings, Online Presences, Physical Presences). 2. Bizzy sends the existing business context to the LLM and asks for **1–5 suggestions** for that section. 3. A modal shows the suggestions. Select the ones you want. 4. Click **Add** — the selected items are created in a single batch operation. The LLM is instructed to avoid duplicating items you already have, so repeat clicks generally produce new ideas rather than the same ones again. ## What gets sent to the LLM * Your business name * Business description * Industries you've selected * Other entities already on the page (for context and to avoid duplicates) Nothing is sent except what you've already typed into the Business page. ## Per-type behavior | Block | Typical suggestions | | ---------------------- | -------------------------------------------------------- | | **Name** | Cleaner or more formal versions of what you typed | | **Description** | A drafted paragraph based on name + industries | | **Industries** | Categories that might apply given name + description | | **Offerings** | 3–5 likely products/services based on industries | | **Online presences** | Guessed URLs for website and common social platforms | | **Physical presences** | Rarely useful — the LLM doesn't know your real addresses | ## Rate limiting Suggestions are rate-limited to **10 requests per minute per user**. If you hit the limit, wait a minute and try again. ## When to trust suggestions * **Always review.** Especially URLs and addresses — AI guesses can look right and be wrong. * **Prefer editing to accepting verbatim.** The suggestion is a draft; shape it to match your actual business. * **Combine with manual input.** Use suggestions to start a section, then edit. ## Next steps Review the core fields Iterate on what you sell # Business Source: https://docs.bizzyco.ai/user-guide/businesses/index Describe your business to Bizzy so agents and automations have accurate context The **Business** page is a single source of truth for what your organization does, where it operates, and how it sells. Agents, automations, and AI suggestions all reference this information, so filling it in meaningfully pays dividends across the product. Business profile page ## What lives on this page Name, description, industries Products and services you sell Online and physical locations LLM-generated drafts for every section Link your Stripe account for customer sync ## Why this matters When an agent drafts an email, when an automation classifies a message, when the platform shows you a Customers list — they all use Business information to ground their behavior in your actual context. A generic "we're a business" profile produces generic outputs; a detailed profile with offerings, presences, and industries produces outputs that actually sound like you. ## Where this data is used * **Agents** read the business profile as part of their context when composing replies. * **Automations** use offerings and industries to classify and route inbound messages. * **Customers** sync from Stripe is scoped to the primary business (via Stripe Connect). ## Next steps Start with the essentials Let Bizzy draft your profile # Offerings Source: https://docs.bizzyco.ai/user-guide/businesses/offerings Describe the products and services your business sells Offerings are the products and services you provide. Bizzy uses them when classifying inbound messages, drafting outbound replies, and surfacing relevant context to agents. Offerings list ## Per-offering fields | Field | Notes | | --------------- | ------------------------------------------------------ | | **Name** | Short label — "Basic Tune-Up", "Enterprise Onboarding" | | **Description** | Prose description of what the offering includes | | **Is service** | Toggle — `true` for services, `false` for products | The service vs. product toggle affects how agents phrase things (for example, "the service lasts 2 hours" vs. "the product ships in 2 days"). ## Adding offerings 1. Scroll to the **Offerings** block on the Business page. 2. Click **Add Offering**. 3. Fill in name, description, and the service toggle. 4. Save. ### Bulk add with AI suggestions Instead of typing each offering, click **Suggest** on the Offerings block. Bizzy returns 1–5 offerings based on your business profile; select the ones to add and commit them all at once. ## Editing Click any offering row to edit in place. Changes save on the next **Save** click. ## Removing Use the row menu → **Delete** to remove an offering. Deletion is immediate. ## Tips * Stay concrete. "Consulting" is weaker than "Monthly retainer: weekly 30-min calls + Slack support". * Keep descriptions short enough that an agent's context window can include several of them at once. ## Next steps Online and physical locations Draft offerings with the LLM # Online and Physical Presences Source: https://docs.bizzyco.ai/user-guide/businesses/presences Link websites, social accounts, listings, and physical addresses to your Bizzy business Presences tell Bizzy where your business shows up in the world — online and offline. Agents and automations use them for context and to build accurate replies (e.g., embedding your website URL in a signature). ## Online presences Each online presence has: | Field | Notes | | --------------- | -------------------------------------------------------------------------------- | | **URL** | Full URL, including `https://` | | **Type** | `Website`, `Social`, or `Listing` | | **Provider** | Brand label when applicable (Facebook, Instagram, Google Business Profile, etc.) | | **Description** | Optional prose context | Typical examples: * **Website:** `https://yourbusiness.com` * **Social:** your Instagram / LinkedIn / Facebook pages * **Listing:** Google Business Profile, Yelp, industry directories ### Adding Click **Add Online Presence** on the Business page. Pick a type and provider; paste the URL; save. ### AI suggestions The **Suggest** button on the Online Presences block proposes likely URLs based on your business name. These are best-guesses and may or may not actually belong to you. AI-generated URLs can be wrong or impersonate other businesses. Always review suggestions before accepting — the UI displays a disclaimer for this reason. ## Physical presences Each physical presence has: | Field | Notes | | --------------- | ----------------------------------------------------------------------- | | **Address** | Street / city / state / ZIP (or local equivalent) | | **Description** | Optional context — "main office", "east bay service area", "storefront" | Use physical presences for any location that matters to your business — offices, shops, service areas, warehouses. ### Adding **Add Physical Presence** → fill in address → save. ### AI suggestions Physical suggestions are weaker than online ones because the LLM has less reliable signal. Review carefully. ## Next steps How suggestions work across the page Link Stripe for customer sync # Business Profile Source: https://docs.bizzyco.ai/user-guide/businesses/profile Name, description, and industries for your Bizzy business The profile block is the core "who are you" section. Agents and automations read these fields directly when they need context about your organization. ## Fields ### Name Your business's public name. Agents use this in greetings and signatures. ### Description A longer prose description — what you do, who you serve, and how. This is a rich-text editor, so you can use headings, lists, and emphasis. Keep the description specific. "A company that sells things" gives agents nothing to work with; "a small roofing company in Northern California that handles residential replacements and inspections" gives them plenty. ### Industries A multi-select tag input. Pick every industry that fits — you can (and should) select multiple if your business straddles categories. Industries are stored on the business profile and feed into: * Automation classification (e.g., "is this a sales or support inquiry?") * AI suggestions across other sections * Customer segmentation ## Saving Edits save via the **Save** button under each block. Validation is light — only the name has a length cap. ## Using AI suggestions Every field supports AI suggestions — see [AI Suggestions](/user-guide/businesses/ai-suggestions). For the profile, suggestions draft a description and propose industries based on whatever you've already filled in. ## Next steps Add what you sell Add where you sell # Stripe Connect Source: https://docs.bizzyco.ai/user-guide/businesses/stripe-connect Link your Stripe account to Bizzy to sync customers and payments Stripe Connect is the OAuth handshake that lets Bizzy read customer data from your Stripe account. Once linked, your Stripe customers appear in the [Customers](/user-guide/customers/index) section. Stripe Connect card on the Business page ## Prerequisites * An existing Stripe account. If you don't have one, create it at [stripe.com](https://stripe.com). * Owner or Admin role in Bizzy — the Stripe Connect card is visible to everyone, but connecting runs under Owner/Admin authority. ## Connecting 1. Scroll to the **Stripe Connect** card on the Business page. 2. Click **Connect Stripe**. A Stripe-hosted page opens in a new tab. 3. Log in to Stripe and confirm the connection. 4. Stripe redirects you back to Bizzy. The card now shows your Stripe account as linked. Every customer sync and billing action is scoped to the connected Stripe account. ## What Connect enables * **Customer sync.** Stripe customers flow into Bizzy [Customers](/user-guide/customers/index). * **Account metadata.** Stripe's payout currency, country, and other profile fields become visible. ## What Connect does *not* do * **Bizzy's billing.** Your Bizzy subscription is unaffected by the Connect link. You still pay Bizzy separately — see [Admin Guide → Billing](/admin-guide/billing/index). * **Write to Stripe.** Today, sync is read-only from Stripe → Bizzy. There is no "create customer in Stripe from Bizzy" flow. ## Disconnecting Revoke the connection from your Stripe dashboard (Settings → Connected Accounts). When you revoke, Bizzy loses read access; existing synced customer records remain in your Customers list but no longer update. ## Troubleshooting | Problem | Likely cause | Fix | | -------------------------------- | ------------------------------------ | ---------------------------------------------- | | OAuth popup blocked | Browser blocker | Allow popups from Bizzy and retry | | "Connection failed" after Stripe | Stripe account requires verification | Complete Stripe onboarding, then retry | | Customers don't appear | Sync in progress | Wait a few minutes; initial sync can take time | ## Next steps See your synced customers How sync actually works # Contacts Source: https://docs.bizzyco.ai/user-guide/contacts/index Manage your contacts in Bizzy Bizzy's contact management helps you organize and maintain information about the people you communicate with. Store contact details, track conversation history, and build relationships with your business contacts. ## Features | Feature | Description | | ---------------- | ------------------------------------------ | | Contact Profiles | Store names, companies, and job titles | | Multiple Emails | Track multiple email addresses per contact | | Phone Numbers | Store phone numbers with country codes | | Addresses | Save physical addresses for contacts | | Message History | View all messages with each contact | | Profile Images | Add photos to contact profiles | ## Getting Started Add, edit, and organize your contacts ## Contact Data Each contact in Bizzy can include: * **Name** - First name, last name, and display name * **Company** - Organization or business affiliation * **Job Title** - Professional role or position * **Email Addresses** - Multiple emails with labels (work, personal, etc.) * **Phone Numbers** - Multiple numbers with country codes * **Addresses** - Physical addresses with full details * **Notes** - Internal notes about the contact * **Profile Picture** - Visual identifier for the contact ## Automatic Contact Creation Bizzy automatically creates contact records when: * You receive an email from a new sender * You send an email to a new recipient These auto-created contacts can be enriched with additional details as needed. Contact data is scoped to your organization. Team members with appropriate permissions can view and edit shared contacts. # Managing Contacts Source: https://docs.bizzyco.ai/user-guide/contacts/managing Add, edit, and organize contacts in Bizzy This guide covers how to create, edit, and manage contacts in Bizzy. Keep your contact information organized to improve communication and enable powerful automations. Bizzy contacts list ## Viewing Contacts Access your contacts from the main navigation: 1. Click **Contacts** in the sidebar 2. Browse the contact list or use search to find specific contacts 3. Click a contact to view their full profile The contact list displays: * Contact name and profile picture * Company and job title * Primary email address * Quick action buttons ## Adding a New Contact To create a new contact: 1. Navigate to **Contacts** 2. Click the **Add Contact** button 3. Fill in the contact details: * First name and last name * Company and job title * Email addresses * Phone numbers * Addresses 4. Click **Save** to create the contact ### Required Fields At minimum, a contact needs one of the following: * First name or last name * Email address All other fields are optional and can be added later. ## Editing Contact Details Contact detail view ### Basic Information To edit a contact's basic information: 1. Open the contact profile 2. Click **Edit** or click directly on the field you want to change 3. Update the information: * **First Name** / **Last Name** - The contact's name * **Company** - Their organization or employer * **Job Title** - Their role or position * **Title** - Honorific prefix (Mr., Ms., Dr., etc.) * **Notes** - Internal notes about this contact 4. Changes save automatically ### Profile Picture Add or change a contact's profile picture: 1. Open the contact profile 2. Click the profile picture area or the **Upload Image** button 3. Select an image file from your computer 4. The image uploads and displays on the profile Supported formats: JPG, PNG, GIF (max 5MB) ## Managing Email Addresses Contacts can have multiple email addresses with labels. ### Adding an Email 1. Open the contact profile 2. Navigate to the **Emails** section 3. Click **Add Email** 4. Enter the email address 5. Optionally add a label (e.g., "Work", "Personal") 6. Click **Save** ### Editing an Email 1. Find the email in the contact's profile 2. Click the **Edit** button next to the email 3. Update the address or label 4. Click **Save** ### Deleting an Email 1. Find the email in the contact's profile 2. Click the **Delete** button 3. Confirm the deletion Deleting an email address also removes its association with message history. The messages remain but won't be linked to this contact via the deleted email. ## Managing Phone Numbers Store multiple phone numbers with international support. ### Adding a Phone Number 1. Open the contact profile 2. Navigate to the **Phone Numbers** section 3. Click **Add Phone Number** 4. Enter the phone number 5. Select the country code 6. Click **Save** ### Phone Number Format Phone numbers are stored with: | Field | Description | Example | | --------------- | -------------------- | ----------------- | | Phone Number | Full number | +1 555 123 4567 | | Country Code | International prefix | +1 (US), +44 (UK) | | National Number | Local format | 555 123 4567 | ## Managing Addresses Store physical addresses for contacts. ### Adding an Address 1. Open the contact profile 2. Navigate to the **Addresses** section 3. Click **Add Address** 4. Fill in the address fields: * Address Line 1 (street address) * Address Line 2 (apartment, suite, etc.) * City * State/Province * Postal Code * Country 5. Click **Save** ### Address Fields | Field | Description | Required | | -------------- | ------------------ | -------- | | Address Line 1 | Street address | No | | Address Line 2 | Additional info | No | | City | City name | Yes | | State | State or province | No | | Postal Code | ZIP or postal code | No | | Country | Country name | Yes | ## Viewing Message History See all communications with a contact: 1. Open the contact profile 2. Navigate to the **Messages** section 3. Browse messages sent to/from this contact 4. Click a message to open it in the inbox Messages are displayed chronologically with: * Date and time * Subject line * Message preview * Direction (incoming/outgoing) ## Deleting Contacts To remove a contact from your organization: 1. Open the contact profile 2. Click **Delete Contact** (usually in a menu or at the bottom) 3. Confirm the deletion Deleting a contact is a soft delete. The contact is removed from views but data is preserved for compliance. Contact support if you need permanent deletion. ## Troubleshooting ### Contact Not Saving | Issue | Cause | Solution | | ------------------------- | ----------------------- | ------------------------------------------ | | Save button disabled | Required fields missing | Ensure name or email is provided | | Error on save | Invalid data format | Check email format and phone number format | | Duplicate contact warning | Contact already exists | Search for existing contact and merge | ### Missing Contacts | Issue | Cause | Solution | | --------------------- | -------------------- | ----------------------------------- | | Contact not appearing | Search filter active | Clear search and filters | | Contact deleted | User removed contact | Contact cannot be recovered by user | ## Next Steps View messages from your contacts Create automated workflows for contacts # Customers Source: https://docs.bizzyco.ai/user-guide/customers/index Browse customers synced from your Stripe account into Bizzy The **Customers** section shows the customers on your primary business's Stripe account. Think of it as a CRM-style view over Stripe data — unified with the rest of Bizzy so agents and automations can reference customer context. Customers list with Stripe-synced badges ## The list Each row shows: | Column | Notes | | ------------------ | -------------------------------------------- | | **Name** | From Stripe | | **Email** | From Stripe | | **Customer since** | Stripe creation date | | **Stripe badge** | Green badge if the row is synced from Stripe | ### Filters * **Search** — matches name and email. * **Sync filter** — `All` / `Synced from Stripe` / `Not synced`. ## Customer detail Click a row to open the customer's detail page. You'll see: * Contact information (name, email) * Stripe-sourced metadata (customer since, Stripe customer ID if synced) * Related context from Bizzy when applicable ## Prerequisites For the Customers section to be populated, you need: 1. A linked Stripe account — see [Stripe Connect](/user-guide/businesses/stripe-connect). 2. Customers in that Stripe account. If Stripe isn't linked yet, the list will be empty and you'll see guidance pointing you to connect. ## Limitations today * **Read-only from Stripe.** The current UI displays Stripe customers — it doesn't create them. New customers show up only after they exist in Stripe. * **No manual "sync now".** Sync happens automatically; there's no button to force an immediate refresh. * **No customer ↔ contact mapping.** Customers and [Contacts](/user-guide/contacts/index) are separate entities today; linking them explicitly is not yet supported in the UI. ## Next steps Understand the data flow Link Stripe to populate this list # How Customer Sync Works Source: https://docs.bizzyco.ai/user-guide/customers/sync The data flow between Stripe and Bizzy Customers Customer sync is **Stripe → Bizzy**, scoped to your primary business's connected Stripe account. ## What triggers a sync * **Initial sync** runs when you first connect Stripe — existing customers are imported in a batch. * **Ongoing sync** runs on Stripe webhooks. New customers and updates to existing customers propagate to Bizzy automatically. There is no manual "sync now" button today. Webhook propagation is usually within seconds. ## Sync scope * Only the Stripe account you linked via [Stripe Connect](/user-guide/businesses/stripe-connect) is synced. * The linked account is scoped to your **primary** business. In a multi-business setup, the other businesses' customers don't appear here. ## What gets synced * **Name** * **Email** * **Customer ID** (`stripeCustomerId`, used to detect that a row is synced) * **Customer creation date** (displayed as "Customer since") Stripe-specific metadata that Bizzy doesn't surface today (tax IDs, shipping addresses, metadata keys) remains in Stripe. Contact support if you need a specific field pulled through. ## Detecting sync status * **Synced** customers have a green **Stripe** badge in the list and a populated `stripeCustomerId`. * **Not synced** customers are rows added in Bizzy directly — today this path is rare because the UI doesn't expose customer creation, but some API/MCP callers do. The **Sync filter** in the list lets you narrow to synced or not-synced. ## What does NOT sync * **Bizzy → Stripe.** Edits in the Customers list do not push back to Stripe. Customer data in Stripe is authoritative. * **Deletion.** Deleting a customer in Stripe does not delete the Bizzy record automatically — it stays visible until support removes it (or a future sync pass handles soft-deletes). ## When sync breaks | Symptom | Likely cause | Fix | | ----------------------------------------- | ------------------------------------ | ---------------------------------------------------------------------- | | New Stripe customer not showing | Webhook delivery delay or failure | Wait a few minutes; if still missing, check Stripe's event log | | Stripe disconnected | OAuth revoked | Reconnect from [Stripe Connect](/user-guide/businesses/stripe-connect) | | Initial import didn't populate everything | Rate limits on large Stripe accounts | Contact support | ## Next steps Back to the list view Link or relink Stripe # Manage Domains with AI Source: https://docs.bizzyco.ai/user-guide/domains/ai Ask a Bizzy agent to search, register, verify, and renew domains and manage DNS — with approvals and spend ceilings on anything that costs money New Bizzy agents can run the whole domain lifecycle for you: find an available name, register it, verify a domain you own elsewhere, manage its DNS records, and renew it before it expires. The same tools work in [agent chat](/user-guide/agents/chat) and over the [Bizzy MCP server](/mcp-server/introduction), and they use the exact same backend as the UI and REST API — an agent-registered domain looks no different from one you bought yourself. Anything that spends money — registering or renewing — is held to the approval and spend-ceiling model described in [Approvals and spending](#approvals-and-spending) below. ## Find and register a domain An agent can check availability and live pricing for names and TLD variants with [`searchDomainAvailability`](/mcp-server/tools/domains#searchdomainavailability), then register the one you pick with [`registerDomain`](/mcp-server/tools/domains#registerdomain) — the same quote → charge → provision flow as the UI. Try prompts like: > Is acmeplumbing.com available? Check .co and .io too, and show me prices. > Register acmeplumbing.com for 2 years if it's under \$30. Use our business > address for the WHOIS contact. The agent searches first, uses the quoted prices to set the registration's spend ceiling — a multi-year registration totals the first year at the registration price plus each additional year at the renewal price (see [What you pay](/user-guide/domains/register#what-you-pay)) — and, at the default **Ask** permission, asks for your approval before anything is charged (see [Approvals and spending](#approvals-and-spending)). WHOIS privacy and auto-renewal are on by default. Initial DNS is configured automatically, so the domain is ready for [email addresses](/user-guide/email-addresses/bizzy-hosted) once it's active. ## Verify a domain you own elsewhere For a domain registered at another provider, an agent first adds the domain to Bizzy with [`createDomain`](/mcp-server/tools/domains#createdomain) (if it isn't there already), then starts ownership verification with [`verifyDomain`](/mcp-server/tools/domains#verifydomain). Verification returns the TXT record you need to publish at your DNS host, then checks for it — verification also keeps being re-checked hourly in the background, and the agent can poll for the result at any time. > Verify getbizzy.net — give me the TXT record I need to add at Cloudflare. > Has getbizzy.net finished verifying yet? A verification token lasts 7 days; if it expires before the record shows up, asking again starts a fresh one. See [Verify a domain](/user-guide/domains/verify) for the underlying flow. ## Manage DNS records For domains **registered through Bizzy**, an agent can list, create, update, and delete DNS records ([`listDnsRecords`](/mcp-server/tools/domains#listdnsrecords), [`createDnsRecord`](/mcp-server/tools/domains#creatednsrecord), [`updateDnsRecord`](/mcp-server/tools/domains#updatednsrecord), [`deleteDnsRecord`](/mcp-server/tools/domains#deletednsrecord)). The DNS zone is created automatically the first time a record is added. This is handy for the fiddly records other services ask you to add: > Add the TXT record Stripe gave me to acmeplumbing.com: > `stripe-verification=4c22…` > Point acmeplumbing.com at 203.0.113.7 and www at the root domain. > What DNS records does acmeplumbing.com have right now? Domains verified with Bizzy but hosted elsewhere keep their DNS at your provider — the agent can tell you what to add (as in the verification and [deliverability](/user-guide/domains/deliverability) flows) but can't change records there. See [Managing DNS Records](/user-guide/domains/dns) for the supported record types and cautions around email-critical records. ## Renew a registration An agent can preview a renewal price with [`getDomainRenewalPrice`](/mcp-server/tools/domains#getdomainrenewalprice) and renew with [`renewDomain`](/mcp-server/tools/domains#renewdomain), which charges the account's default payment method and extends the expiration date. If the registrar renewal fails after the charge, the charge is refunded automatically. > What would it cost to renew acmeplumbing.com for 3 years? > Renew acmeplumbing.com for a year if it's still under \$20. Registered domains auto-renew by default, so manual renewal is mostly for domains where you've turned auto-renew off or want to extend further ahead. ## Approvals and spending Two domain tools spend real money: `registerDomain` and `renewDomain`. Three independent safeguards keep an agent from spending more than you intend: 1. **A hard spend ceiling per call.** Both tools require `maxAmountCents`. If the live price already exceeds it, the call fails with `PRICE_EXCEEDS_MAXIMUM` and nothing is charged. The ceiling is enforced again right before the actual charge, so if the price rises after a renewal is queued, the renewal fails instead of charging above your ceiling. 2. **Preview before commit.** Each spend tool has a read-only pricing counterpart (`searchDomainAvailability` for registration, `getDomainRenewalPrice` for renewal) the agent uses to quote first and pick the ceiling. Retries reuse an idempotency key, so a retried call replays the original result instead of charging twice. 3. **Human approval.** Both tools default to **Ask**, so in agent chat you get an [inline approval card](/user-guide/agents/chat) — showing the exact tool input, including the ceiling — before anything is charged. External MCP clients have no approval step, so over MCP these tools are hidden unless you explicitly set their permission to **Allow**. Each has its own permission (`domain-registrations.purchase` and `domain-registrations.renewal`) that is never inherited from a broader grant — allowing other domain tools does not enable spending. The remaining domain tools follow the standard model — reads default to **Allow**, writes to **Ask** — and every level can be changed per agent. See [Tool Permissions](/user-guide/agents/tool-permissions) for how the Allow / Ask / Deny model works. Domain intent → tool sequence quick reference: **register a domain**: `searchDomainAvailability` (get prices) → `registerDomain` with `maxAmountCents` ≥ `registrationPrice + renewalPrice × (periodYears − 1)` (search prices are per-year; a ceiling set from `registrationPrice` alone under-prices multi-year registrations) and a fresh `idempotencyKey`. **verify an external domain**: `createDomain` (if the domain is not in Bizzy yet) → `verifyDomain` (returns the TXT record to publish; call again to poll). **change DNS**: `listDnsRecords` → `createDnsRecord`/`updateDnsRecord`/`deleteDnsRecord` (Bizzy-registered domains only). **renew**: `getDomainRenewalPrice` → `renewDomain` with `maxAmountCents` from the quote and a fresh `idempotencyKey`. Spend tools fail closed: if the live price exceeds the ceiling, nothing is charged. Parameter semantics live at `/mcp-server/tools/domains`. ## Next steps Parameters, permissions, and return shapes for every domain tool Set Allow, Ask, or Deny per tool on each agent # Domain Billing History Source: https://docs.bizzyco.ai/user-guide/domains/billing Charge history and receipts for domain registrations and renewals New Every domain registration and renewal charge is recorded, with a receipt you can open, print, or save. Domain charges are **not** on the [Purchases](/user-guide/purchases/index) page. Domains are account resources that persist and renew, so their billing history lives with the domains themselves — per domain on the detail page, and account-wide at **Domains → Billing History**. ## Per-domain history Open a registered domain from the [Domains](/user-guide/domains/index) page and select the **Billing** tab. Each row shows: | Column | Notes | | ----------- | --------------------------------------------------- | | **Date** | When the charge happened | | **Type** | `Registration` or `Renewal` | | **Amount** | Total charged | | **Status** | `Paid`, or `Refunded` if the charge was compensated | | **Actions** | Open the receipt | The Billing tab only appears on domains registered through Bizzy — verified-only domains are never charged. ## Account-wide history Click **Billing History** on the Domains page to see every domain charge in your organization in one paginated list, including charges for domains that were later deleted or whose registration was refunded before completing. Domain names link back to the domain's detail page. ## Receipts Click **Receipt** on any charge to open the Stripe-hosted receipt in a new tab. From there you can print it or save it as a PDF. ## Refunds If a registration or renewal fails after payment — for example, the registrar rejects the registration — Bizzy refunds the charge automatically and the row shows **Refunded**. The receipt reflects the refund too. Only registration and renewal charges exist today. If other domain charge types (such as transfers) are introduced, they will appear in the same history. ## Next steps Search, price, and buy a domain Payment methods and subscription invoices # Registration Contacts Source: https://docs.bizzyco.ai/user-guide/domains/contacts Manage the registrant details ICANN requires for domains you register through Bizzy New Every domain you register needs a registrant — a real person or organization, with a reachable email address. Registration contacts are where those details live. These are not the same as your [CRM contacts](/user-guide/contacts/index). A registration contact exists to satisfy the domain registry, and parts of it appear in the public WHOIS record for the domain. ## Where to find them Open a registered domain from the [Domains](/user-guide/domains/index) page and click **Manage Domain Contacts** on the Overview tab. Registration contacts belong to your organization, not to a single domain, so the same contact can be the registrant for as many domains as you like. The one currently serving as this domain's registrant is marked **Registrant for this domain**. The Contacts page is only available for domains registered through Bizzy. For a domain you verified but registered elsewhere, the registrant is managed wherever you bought it. ## Adding a contact Click **Add Contact** and fill in the form. Everything except the organization name, job title, second address line, and label is required — the registry rejects an incomplete registrant. | Field | Notes | | ---------------- | --------------------------------------------------------- | | **Name** | The registrant's legal first and last name | | **Organization** | Optional. If you set it, a job title is required too | | **Email** | Must be reachable — ICANN verification is sent here | | **Phone** | International format, e.g. `+15555550123` | | **Address** | Street, city, state or province, postal code, and country | | **Label** | Optional, for your own organization. Never leaves Bizzy | Some extensions ask for extra details — a `.us` domain needs a nexus category, for example. Those fields appear automatically once Bizzy knows the extension. ## Editing a contact Changes are sent to the registry, so what you see in Bizzy and what the world sees in WHOIS stay the same. If the change can't be applied, nothing is saved on either side and the form tells you why. Changing the registrant's **name**, **organization**, or **email** restarts ICANN's registrant email verification. A confirmation email goes to the new address, and you have 15 days to click the link. Miss it and the registry can suspend the domain. Address and phone changes don't trigger this. Because a contact can be the registrant for several domains, that 15-day clock restarts on **every** domain using it. Each one shows its own verification banner, and you'll get a reminder 7 days and 2 days before the deadline. See [Registering a Domain](/user-guide/domains/register) for more on the verification email itself. Some contacts can't be edited after registration — the **Edit Contact** option is greyed out with a note when that's the case. Create a new contact instead and use it for your next registration. ## Deleting a contact A contact that is still the registrant of one of your domains can't be removed. Bizzy names the domains that are using it so you know where to change the registrant first. Once no domain depends on it, deleting the contact removes it from Bizzy and from the registry. ## Next steps Search, price, and buy a domain The audit trail for registrant changes # Email Deliverability (SPF, DKIM, DMARC) Source: https://docs.bizzyco.ai/user-guide/domains/deliverability Check and fix the SPF, DKIM and DMARC records that decide whether mail from your domain reaches the inbox New Mailbox providers (Gmail, Outlook, and others) only trust mail from a domain that authenticates correctly. Three DNS records do that work: * **SPF** — lists who is allowed to send for your domain. * **DKIM** — cryptographically signs your mail so it can't be tampered with. * **DMARC** — tells receivers what to do with mail that fails SPF or DKIM, and is increasingly required by major providers. If these aren't right, your mail lands in spam or is rejected outright. Bizzy surfaces the status of all three per domain, so you always know whether a domain is ready to send. ## Where to find it Open a domain from **Domains**, then go to the **Settings** tab. The **Email Authentication** panel shows an overall verdict and the status of each record. Email authentication panel showing SPF, DKIM and DMARC status The verdict is one of: | Verdict | What it means | | ------------------ | ---------------------------------------------------------------------------- | | **Ready to send** | Every required record is verified — the domain can send and receive | | **Setting up** | Authentication is being configured; this can take a few minutes | | **Almost ready** | Your records are published, but the email provider hasn't confirmed them yet | | **Action needed** | Setup didn't complete — the message on the panel says why | | **Not configured** | Email isn't enabled on this domain yet | **Action needed** distinguishes two very different situations. If your DNS records are missing or failed verification, add the records listed below the panel, then click **Retry setup** to run verification again — **Re-check** only refreshes the current status and can't restart a verification that has already failed. If setup failed on Bizzy's side instead (a provider or configuration problem), the panel says so explicitly — your DNS is not the problem, and the fix is the same **Retry setup**, or contacting support if it keeps failing. **Almost ready** means there is nothing left for you to add: every required record resolves publicly, but the email provider has not accepted them yet. Click **Retry setup** to run verification again. **Retry setup** is available whenever setup has failed, whatever the reason. ### Record status Each record row carries its own status, so you can see exactly which one is holding the domain back: | Status | What it means | | ---------------- | --------------------------------------------------------------------- | | **Verified** | The email provider accepted this record | | **Found in DNS** | The record resolves publicly, but the provider hasn't accepted it yet | | **Pending** | Expected, not confirmed yet | | **Missing** | Expected and not found — add it from the details shown on the row | | **Auto-managed** | Bizzy controls the DNS zone and maintains this record for you | | **Recommended** | Optional but advised (DMARC on domains you host DNS for elsewhere) | **Found in DNS** is deliberately distinct from **Verified**: publishing a record is not the same as the provider accepting it, and a domain can have every record published while still being unable to send. DMARC is the exception — Bizzy checks it directly, so a published policy shows as **Verified**. ### Every required record must verify A domain is ready only once **all** of its required records verify — sending (SPF + DKIM) and receiving (the inbound `MX`) alike. If your domain already has `MX` records pointing at another mail host such as Google Workspace or Microsoft 365, they conflict with the inbound record and setup will report a failure until that's resolved. Consider using a subdomain for Bizzy email instead, which avoids the conflict entirely. ## Registered vs. verified domains How you manage these records depends on how the domain got into Bizzy: * **Registered through Bizzy** — Bizzy controls the DNS zone, so SPF, DKIM and DMARC are added and kept in sync **automatically**. The panel shows each record as **Auto-managed**; there is nothing for you to do. * **Verified (DNS hosted elsewhere)** — you add the records yourself. The panel shows the exact **name**, **type** and **value** for each record, with a copy button. Names are shown as the label to enter at your DNS host — most providers append your domain automatically — and `@` means the domain itself. Add them at your DNS provider, then re-check. ## The records For a verified domain you'll add **every record the panel lists** — email on Bizzy covers receiving as well as sending, so alongside SPF and DKIM there is an MX record that routes inbound mail for your domain to Bizzy. Add each one exactly as shown (MX records include the priority displayed). DMARC is handled differently depending on whether your domain already publishes a policy: | Record | Type | Notes | | ------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------- | | **SPF** | `TXT` + `MX` | Authorize Bizzy to send for your domain and route bounce feedback; both live on a sending subdomain (e.g. `send.`) | | **DKIM** | `TXT` | Publishes the public key used to verify your mail's signature | | **Receiving** | `MX` | Routes inbound mail to Bizzy — published at your domain itself (name `@`) | | **DMARC** | `TXT` | Published at `_dmarc.` — see below | **If your domain already publishes DMARC**, Bizzy detects it and shows the record as **Verified** with your own policy value. Your existing policy is never overwritten, duplicated, or replaced with a weaker one — this applies to registered domains too, where Bizzy otherwise manages the zone. **If no DMARC policy exists yet**, Bizzy recommends a safe starting policy (and writes it to the zone automatically for registered domains): ```dns theme={null} _dmarc.example.com. IN TXT "v=DMARC1; p=none;" ``` DMARC handling: an existing `_dmarc.` policy is detected during setup and on every re-check, shown as Verified with the domain's own value, and never overwritten or duplicated. Only when no policy exists is the starter recommended (and auto-provisioned for registered domains): name `_dmarc.`, type `TXT`, value `v=DMARC1; p=none;`. `p=none` is monitoring mode — receivers report on, but do not quarantine or reject, failing mail. Tighten to `p=quarantine` or `p=reject` once alignment is confirmed. `p=none` is **monitoring mode**: it asks receivers to report on failures without sending mail to spam. It's the right place to start on a new domain. Once you're confident everything authenticates, you can tighten the policy to `p=quarantine` or `p=reject` at your DNS provider — Bizzy picks up the change on the next re-check. ## Re-checking Bizzy checks for your records automatically. During setup the checks run frequently in the first hour after you enable email, and the panel updates live as setup progresses, so you don't need to refresh the page. Once the domain is verified, every sending domain is re-validated on a schedule — roughly once a day — so authentication that breaks later doesn't go unnoticed. To force a fresh look at any time, click **Re-check**: Bizzy reads the latest verification status from its sending provider and resolves each record live over DNS — including DMARC, where the observed policy is saved so the panel keeps reflecting it — and updates the status. If the DMARC lookup itself can't complete (a temporary DNS hiccup), the previously saved policy stays in place rather than being cleared. DNS changes can take a few minutes to propagate, so if a record you just added still shows as missing, wait a little and re-check. **Re-check** never starts a new verification — it only refreshes what Bizzy can already see. If verification has failed and you've since corrected your records, click **Retry setup** to run it again. ## If authentication breaks later DNS can drift after a domain goes live — a record edited at your DNS host, a rotated key, a DMARC policy that was removed. When a scheduled re-validation (or a manual **Re-check**) finds previously verified records no longer valid, the panel flips to **Action needed** and names the records at fault. When the scheduled check is what catches the breakage, organization owners and admins also receive an **Authentication broken** notification (see [Notifications](/admin-guide/notifications)); a manual **Re-check** updates the panel you're already looking at without sending one. A DMARC policy only counts as broken if Bizzy had previously seen one published — removing a policy you never added is not flagged, and a temporary DNS hiccup never triggers an alert on its own. To fix it, restore the records shown in the panel (the values are copyable), then click **Re-check** — the warning clears as soon as the records verify again, or automatically on the next scheduled check. ## Before you create an email address When you add an email address, only domains that are **ready to send** appear in the domain picker. If a domain has email setup underway but not finished, a warning lists it with its current status and a link straight to its settings, so you can finish authentication before relying on it. ## Removing a domain Deleting a domain also retires its email configuration: Bizzy revokes the sending credential it created for the domain and removes the domain from the email provider. This happens however the domain is deleted — from the app, the API, by asking your agent, or automatically when a registered domain is removed at the registrar. If the email provider is unreachable at that moment, the deletion still goes through — a provider outage never leaves you with a domain you cannot remove — and Bizzy records any credential it could not revoke rather than losing track of it. A credential recorded that way while email setup is still in progress is retired automatically on the next attempt; one recorded during the deletion itself is kept for support to clear, since the domain is gone by then. What happens to the DNS records depends on how the domain came to Bizzy: * **Externally registered (verified) domains** can be deleted at any time. The DNS records stay at your DNS host — if you're done with the domain, remove the SPF, DKIM, DMARC and MX records listed above yourself; leaving them in place is harmless but advertises a mail setup that no longer exists. * **Domains registered through Bizzy** can only be deleted once the registration has expired and the domain's DNS zone is empty (apart from the records every zone is created with). Disable email for the domain first so Bizzy removes the email records it manages, then delete any remaining records from the domain's DNS tab. The delete option stays unavailable — with an explanation — until the registration expires; if DNS records remain after that, the deletion is refused with a message naming them. A renewal you have already started also blocks the deletion until it finishes. This protects you from losing sight of a registration that is still active — or still renewing — at the registrar. ## Troubleshooting | Problem | Likely cause | Fix | | --------------------------------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Record added but still shows missing | DNS hasn't propagated yet | Wait a few minutes — Bizzy re-checks automatically; **Re-check** any time | | DKIM won't verify | Value copied incompletely — DKIM keys are long | Use the copy button and paste the value exactly, with no added whitespace | | Sending works but mail doesn't arrive | Receiving `MX` record missing or rejected | Add the MX record shown in the panel, including its priority. If your domain already has MX records for another mail host, they conflict — see below | | DMARC shows as recommended | No `_dmarc` record published yet | Add the `_dmarc` TXT record above, then re-check | | DMARC still shows recommended after adding it | The panel hasn't re-checked yet | Click **Re-check** — it then shows **Verified** with your policy | | Panel says setup failed on Bizzy's side | A provider or configuration problem | Your DNS is fine — **Retry setup**, and contact support if it keeps failing | | Verdict stuck on "Setting up" | Verification still in progress | The page updates as setup progresses; **Re-check** forces a fresh look | | Verdict is "Almost ready" and stays there | Records are published but the provider hasn't confirmed them | Click **Retry setup** to run verification again; contact support if it keeps failing | | Records show "Found in DNS", not "Verified" | The provider hasn't accepted them yet | Nothing to add — **Re-check**, then **Retry setup** if it doesn't clear | ## Next steps Once a domain is ready to send For domains registered through Bizzy # Managing DNS Records Source: https://docs.bizzyco.ai/user-guide/domains/dns View and edit DNS records for domains registered through Bizzy For domains you **register through Bizzy**, you can manage DNS records directly from the domain's **DNS** tab — no separate registrar or DNS provider login needed. Bizzy hosts the DNS zone on Cloudflare and applies your changes immediately. DNS management is available for domains **registered through Bizzy**. For domains you only [verified](/user-guide/domains/verify) (hosted elsewhere), manage DNS at your existing provider instead. ## Opening the DNS tab 1. Go to **Domains** and open a registered domain. 2. Select the **DNS** tab. The first time you add a record, Bizzy automatically creates the domain's DNS zone — you don't need to set anything up beforehand. ## Supported record types | Type | Use it for | | ------- | ----------------------------------------------------- | | `A` | Point a name at an IPv4 address | | `AAAA` | Point a name at an IPv6 address | | `CNAME` | Alias one name to another hostname | | `MX` | Route email to a mail server (requires a priority) | | `TXT` | Verification strings, SPF, and other text records | | `SRV` | Service records (requires a priority) | | `CAA` | Restrict which authorities may issue TLS certificates | | `NS` | Delegate a subdomain to other name servers | ## Adding a record 1. Click **Add Record**. 2. Choose the **Type**. 3. Enter the **Name** — use `@` for the root domain (e.g. `example.com`) or a subdomain label (e.g. `www`). 4. Enter the **Content** — the record's value, such as an IP address or target hostname. 5. Optionally set the **TTL** (time-to-live, in seconds). The default is one hour (3600). 6. For `MX` and `SRV` records, set a **Priority**. 7. Save. The record takes effect right away, though DNS resolvers elsewhere may cache the previous value until the TTL expires. ## Editing and deleting records * **Edit** a record to change its value, TTL, or priority. Updates fully replace the record's fields. * **Delete** a record you no longer need. You can select multiple records and remove them together. Editing or deleting records that Bizzy manages for email deliverability (SPF, DKIM, DMARC, and MX records) can stop your email from sending or being delivered. Change those only if you know what you're doing. ## Beyond the dashboard Everything on the DNS tab is also available programmatically: * **REST API** — `GET/POST/PUT/DELETE /v1/domains/{id}/dns-records` (and `/v1/domains/{id}/dns-records/{recordId}`). See the [API reference](/api-reference/introduction). * **MCP / AI** — the `listDnsRecords`, `createDnsRecord`, `updateDnsRecord`, and `deleteDnsRecord` tools. See [Domain Tools](/mcp-server/tools/domains). ## Next steps Buy a new domain through Bizzy Review the audit trail of changes to a domain # Domain Events Source: https://docs.bizzyco.ai/user-guide/domains/events Audit trail of status transitions and actions on a Bizzy domain Each domain has an events timeline on its detail page. The timeline is your audit trail for verifications, registration milestones, and status changes. Domain events timeline ## What shows up Events are logged for the transitions that matter: | Event | Fires when | | ------------------------------ | ----------------------------------------------------------------------------------------------------------- | | Domain created | You added the domain (via verify or register) | | Verification check | The verification workflow ran against DNS | | Verification succeeded | TXT record observed, status moved to active | | Registration purchased | Stripe checkout completed | | Registration activated | The registrar confirmed the registration | | Registration submitted | A new registration completed — the registrar emails the registrant to verify their address (ICANN, 15 days) | | Registrant changed | The registrant contact changed — this re-triggers ICANN registrant email verification | | Registrant notice dismissed | You dismissed the ICANN registrant verification banner | | Status changed | Any transition — pending → active, active → expiring, etc. | | Domain settings updated | You changed auto-renew, WHOIS privacy, or transfer lock | | DNS records updated | You added, changed, or removed a DNS record — or Bizzy set up DNS hosting for the domain | | Email address added | An address was created on the domain | | Email DNS records propagated | Every email DNS record resolved, and verification with the email provider began | | Email authentication rechecked | You re-checked email authentication and the status changed | There is no "registrant verified" event: the registrar doesn't report verification completion, so the timeline records when verification was requested — not when (or whether) it finished. The exact set depends on the source (registered vs. verified) and how old the domain is. ## Reading the timeline * Most recent event appears at the top. * Each event shows a timestamp and a short description. Timestamps are in your local timezone — hover one for the UTC time, relative age, and a copyable ISO string. * One action can record more than one event when it genuinely changes more than one thing. A successful verification writes two: the verification itself, and the status change from pending to active. Both share a timestamp, and their order is stable every time you load the page. ## When this is useful * **Debugging verification.** If a domain stays stuck in pending, the timeline shows what the verification workflow actually saw in DNS. * **Audit.** If a domain unexpectedly lost active status, the timeline tells you when and, often, why. * **Compliance.** If someone asks "when did we add this domain," the answer is here. ## Next steps Back to verification Buy one through Bizzy # Domains Source: https://docs.bizzyco.ai/user-guide/domains/index Verify or register a domain to send email from Bizzy A domain is the piece before the `@` in an email address. Bizzy needs your domain to be verified — and optionally registered through us — before you can send from addresses on it. Domains list ## Two ways to get a domain Add a TXT record at your DNS provider — free Buy through Bizzy — Stripe checkout ## Status states Each domain has a status — visible as a badge in the list: | Status | Meaning | | ---------- | -------------------------------------------------------------------------------------------- | | `pending` | Awaiting verification (TXT record hasn't been seen yet) | | `active` | Verified and healthy — ready for [email addresses](/user-guide/email-addresses/bizzy-hosted) | | `expiring` | Registration renewal due within 7–30 days | | `expired` | Registration has lapsed — domain is non-functional | ## Source The list also shows each domain's source: * **Registered** — bought through Bizzy + Stripe * **Verified** — owned elsewhere; verified via TXT record ## Cost A registered domain is a recurring cost. The **Cost** column shows each registered domain's annual renewal price as **renews \$X/yr** — the same "renews" figure shown during registration — so you can see your domain spend at a glance. Verified-only domains — which you own, pay for, and renew at your own registrar — show a dash in both the **Cost** and **Auto-Renew** columns. Open a domain to see its full cost on the **Overview** tab: * **Registration** — the first-year price. * **Next renewal** — what you'll pay per year to keep the domain. Premium domains carry registry-set pricing and are labelled **Premium** in both the list and the detail view. ## Events Each domain has an events timeline (on its detail page). See [Domain Events](/user-guide/domains/events) for what you can learn from it. ## Filters and search * **Search** — matches domain names. * **Status filter** — narrow to active / pending / expiring / expired. * **Source filter** — all / registered / verified. * **Pagination** — 25 items per page. ## Next steps Add a TXT record at your DNS host Buy one through Bizzy Check SPF, DKIM and DMARC for a sending domain Ask an agent to search, register, verify, renew, and manage DNS # Registering a Domain Source: https://docs.bizzyco.ai/user-guide/domains/register Buy a new domain through Bizzy with Stripe checkout If you don't already own a domain, Bizzy can register one for you. Payment runs through Stripe and the domain is auto-configured for email once the purchase completes. ## When to register vs. verify * **Register** if you're buying a fresh domain specifically for your Bizzy business. * **Verify** if you already own the domain somewhere else. See [Verify a domain](/user-guide/domains/verify). ## The registration flow 1. Go to **Domains** and click **Add Domain** → **Register a new domain** (or visit `/{org}/domains/create` directly). 2. **Search** for a domain. Bizzy checks live availability and shows each available result's first-year price. Domains whose renewal differs from the first year (and all premium domains) also show the **renews at** price, so the cost you see in search is the cost you'll pay. 3. **Pick a name** — if your exact name is taken, Bizzy suggests available **Alternatives**: the same name on other extensions Bizzy sells (`.com`, `.co`, `.io`, etc.) and close variants like `getacme.com` or `acmehq.com`, each with its annual price. When your name *is* available, the same suggestions appear under **You might also like**. Click any name to register it. Premium domains are labelled **Premium** with their registry-set price (see below). 4. **Complete checkout on one page** — the registration page shows everything at once: the registrant contact details required by the domain registry, the registration options, and an embedded Stripe payment form that loads as soon as the page opens. If you have a saved card on file it appears pre-selected for one-click payment; new cards are saved automatically for future checkouts. Apple Pay, Google Pay, and Link appear inside the form when supported by your browser. Changing the registration period briefly reloads the payment form with the new total. 5. **Pay** — click **Pay** to confirm. Your contact details are validated and saved first, then the payment is taken; once it succeeds the page switches to a confirmation view. Domain registration search and TLD picker ## What you pay Domain prices are simple cost-plus over the registrar's wholesale price, and every price you see is all-in: * The **Total cost** shown before payment is exactly the amount charged — there are no separate fees added at checkout. * **WHOIS privacy** is included at no extra cost. The toggle in the registration form controls whether your contact details are hidden from public WHOIS lookups; it never changes the price. * Multi-year registrations are charged as the first year at the registration price plus each additional year at the renewal price, and the registration screen shows both prices along with the total. ## Alternative name suggestions Every search also suggests other names you could register, built from your query: * **Other extensions** — the same name across the TLDs Bizzy sells, in order of popularity (`.com`, `.co`, `.io`, `.net`, `.org`, and more). * **Close variants** — common prefixes and suffixes, like `getacme.com`, `tryacme.com`, `acmeapp.com`, and `acmehq.com`. * **Related names** — suggestions from the domain search provider, filtered to extensions Bizzy sells. Suggestions appear as **Alternatives** when your exact name is taken and as **You might also like** when it's available. Only available names are shown, each with live availability and its first-year price, and clicking one takes you straight into the registration flow. ## Premium domains Some available domains are **premium** — the registry prices them well above a standard domain, and their renewal price is often different from (and higher than) the first-year registration price. Bizzy reads the live premium price from the registrar, so premium domains are handled honestly end to end: * **Flagged in search** with a **Premium** badge and their actual first-year and renewal prices — never a standard placeholder price. * **Charged at the premium amount** at checkout. The total you confirm is the first year at the registration price plus each additional year (when you register for more than one year) at the renewal price — so a multi-year premium registration is quoted exactly, with no surprise at payment. * **Renewed at the premium renewal price**, which is shown on the registration screen and stored with your registration. There's nothing extra to do — pick a premium domain and the prices shown are the prices you pay. ## After purchase When payment is confirmed, the form displays a confirmation view instead of navigating away automatically: * **Heading:** "Payment successful — registering …" * **Body:** "We're registering your domain now. You'll get an email when it's ready, and it will appear on your domains list within a few minutes." * **Button:** Click **Go to domains** to navigate to your Domains list. The domain appears in the list with source **Registered** within a few minutes. Initial DNS is configured automatically — you don't need to add TXT records; Bizzy already controls the zone. The domain transitions to **active** once DNS propagation completes. ## Privacy and security settings Every registered domain gets **WHOIS privacy** and a **transfer lock** by default, managed from the domain's **Settings** tab: * **WHOIS privacy** hides your registrant contact details from public WHOIS lookups. * **Transfer lock** prevents unauthorized transfers to another registrar. * **Auto-renewal** renews the domain automatically before it expires (see [Renewals](#renewals) below). ## Register through the API If you're building an integration or automation, use the [Register a Domain via the API](/api-reference/domain-registration) guide. It shows the full flow: search availability, get a live quote, submit registrant contact details, set `maxAmountCents`, and poll the registration operation. ## Register with AI AI agents can register domains too — searching availability, then running the same quote → charge → provision flow as the UI and API, held to a hard spend ceiling and (in agent chat) your approval before anything is charged. See [Manage Domains with AI](/user-guide/domains/ai) for the full domain × AI story — including the approval and spending model, verification, DNS, and renewal — and the [domain tools reference](/mcp-server/tools/domains#registerdomain) for parameters and permissions. ## Verify your registrant email (ICANN requirement) After a new registration, ICANN requires the registrant email address you provided at checkout to be **verified within 15 days** — otherwise the registry suspends the domain, and its website and email stop working until it's verified. The registrar emails the verification link directly to the registrant contact address — it comes from **[noreply@emailverification.info](mailto:noreply@emailverification.info)**. To stay compliant: 1. Check the registrant contact's inbox (and spam folder) for that email. 2. Click the verification link inside it. That's the whole process. Bizzy can't see whether you've completed verification — registrars don't expose it — so the domain's detail page shows a dismissible notice with your deadline, and you'll receive reminder notifications before day 15. If you already clicked the link, dismiss the notice and ignore the reminders. If you can't find the email, contact support and we'll have it re-sent. A registrant email verification is also re-triggered if the registrant's name, organization, or email is later changed — from the [Registration Contacts](/user-guide/domains/contacts) page, the API, or an agent. Because a contact can be the registrant for more than one domain, the 15-day window restarts on every domain that uses it. ## Renewals * Registered domains renew annually by default via Stripe at their renewal price — for premium domains this is the registry's premium renewal price, not the standard rate. * The list highlights domains entering **expiring** status 7–30 days before renewal. * If an auto-renewal fails (or auto-renew is off), you can renew the domain yourself at any time before it expires — see **Renew now** below. If the domain has already reached **expired**, contact support to recover it. ### Renew now (manual renewal) You can renew a domain yourself at any time — including when auto-renew is off or after a failed auto-renewal: 1. Open the domain's detail page and choose **Renew Domain** from the actions menu (also available from the row menu on the Domains list). 2. Pick a renewal period (1–10 years). The dialog shows the per-year renewal price and the total before you pay — premium domains renew at the registry's premium renewal price and are labelled **Premium**. 3. Confirm. Your account's default payment method is charged the total shown, the registration is extended at the registrar, and the new expiration date appears on the domain once the renewal completes. The price you confirm is a ceiling: if the live registrar price rises above it before the charge happens, nothing is charged — you'll be asked to review the new total and confirm again. You'll get a notification (in-app and email, depending on your preferences) when the renewal succeeds or fails; if the charge fails, the renewal is not processed and the payment is never kept without a successful renewal. ## Troubleshooting | Problem | Likely cause | Fix | | ---------------------------------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | "Domain Unavailable" after clicking a result | The name was registered by someone else between your search and checkout | You're returned to the search page — pick one of the suggested **Alternatives**, or search a different name | | "Something Went Wrong" after clicking a result | Temporary issue confirming availability or pricing — the domain may still be available | You're returned to the search page — try the same name again in a few moments | | Checkout fails | Payment method issue | Update in [Billing](/admin-guide/billing/index) | | Purchase completed but domain stuck in pending | DNS propagation lag | Wait 10–30 minutes; contact support if still stuck after an hour | | Domain suddenly stopped resolving | Registrant email not verified within 15 days | Find the registrar's verification email and click the link; contact support if you can't find it | ## Next steps Use the new domain Verify one you already own # Verifying a Domain Source: https://docs.bizzyco.ai/user-guide/domains/verify Prove ownership of a domain you already have by adding a DNS TXT record Verification proves you control a domain — without this, Bizzy can't let you send from addresses on it. ## Prerequisites * Access to DNS at your domain registrar (or wherever DNS for the domain is hosted). * Permission in Bizzy to add domains (typically Owner or Admin). ## The verification flow 1. Go to **Domains** and click **Verify Domain**. 2. Enter the domain name (for example `example.com`). 3. Save. Bizzy generates a **verification token** for you. Verify domain dialog showing TXT record to add 4. Copy the TXT record Bizzy displays. The record name is `_bizzy` on your domain — for `example.com` that's `_bizzy.example.com` — and the value is `bizzy-domain-verification=` followed by your token. 5. Add the TXT record at your DNS provider. Exact steps vary by host; most providers have a "TXT" record type in their dashboard. Many ask only for the part before your domain, so enter `_bizzy` rather than the full name. 6. Back in Bizzy, click **Check Verification**. The app polls DNS and updates the status once it sees the record. ## Expiry You have **7 days** to complete verification. If the TXT record isn't found by then, the domain's status becomes `failed`. The domain stays in your list — start verification again from the domain's page to get a fresh token. ## Statuses you'll see | Status | What it means for you | | ---------- | ----------------------------------------------------------------------------------------------- | | `pending` | TXT record not yet observed — still waiting | | `verified` | Verified — you can now create [email addresses](/user-guide/email-addresses/bizzy-hosted) on it | | `failed` | The 7-day window lapsed, or the record was missing when checked — start verification again | ## Troubleshooting | Problem | Likely cause | Fix | | ----------------------------------- | ---------------------------- | ------------------------------------------------------------- | | Check keeps saying "not found" | TXT record hasn't propagated | Wait 5–30 minutes; some hosts are slow | | Check finds a different value | Old TXT record cached | Verify at the DNS host that the value matches exactly | | Record is in place but not detected | Record is on the wrong host | The record must be at `_bizzy` on the domain, not on the apex | ## Next steps Use your newly verified domain Buy a new one through Bizzy instead # Bizzy-Hosted Email Addresses Source: https://docs.bizzyco.ai/user-guide/email-addresses/bizzy-hosted Create an email address on a domain you have verified with Bizzy Once a domain reaches **active** status, you can create email addresses on it. Bizzy handles sending and receiving for those addresses — you don't need to run a mail server. ## Prerequisites * At least one domain with **Active** status. See [Domains → Verify](/user-guide/domains/verify). ## Creating an address 1. Go to **Email Addresses** in the sidebar. 2. Click **Add Email Address** (or visit `/{org}/email-addresses/new` for the full-page form). 3. Select **Bizzy** as the provider. The domain dropdown lists only domains that are **ready to send** (email authentication complete). If a domain has setup underway but unfinished, a warning lists it with a link to finish — see [Email deliverability](/user-guide/domains/deliverability). 4. Fill in the form: | Field | Notes | | --------------------- | ----------------------------------------------------------------- | | **Name** | Display name — what recipients see as the "From" | | **Email** | The local part — what comes before the `@` | | **Domain** | Select from your verified domains | | **System email** | Check this if the address is for automated sends and not a person | | **Daily send limit** | Soft cap on sends per day | | **Hourly rate limit** | Soft cap on sends per hour | 5. Click **Save**. Create email address form The new address appears in the list and is ready to use. Messages sent to it land in the [inbox](/user-guide/email/inbox); messages sent from it route through Bizzy's infrastructure, authenticated with the domain's SPF, DKIM and DMARC records. See [Email deliverability](/user-guide/domains/deliverability) for how that authentication is set up and verified. ## Limits The daily and hourly limits exist to keep deliverability healthy. If you regularly hit them, raise them — just be mindful of the reputation impact of large sudden increases on a new domain. ## Removing an address Open the address's detail page and delete it. The underlying domain is unaffected — other addresses on the same domain keep working. ## Next steps Verify or register the domain first Where incoming mail shows up # Email Addresses Source: https://docs.bizzyco.ai/user-guide/email-addresses/index Create Bizzy-hosted email addresses or connect your existing Google / Microsoft account There are two ways to get email flowing in and out of Bizzy: Create `name@yourdomain.com` on a domain you've verified. Sending is handled by Bizzy's infrastructure. Authorize Google Workspace / Gmail or Microsoft 365 via OAuth. Sending stays in your provider's outbox. ## When to pick which | Situation | Recommended | | ---------------------------------------------------------------------------------- | ---------------- | | You own a domain and want a clean `support@`, `hello@`, `info@` address | Bizzy-hosted | | You already use Gmail / Google Workspace for personal email | Connect external | | You already use Microsoft 365 / Outlook | Connect external | | You want automations to send from a generic mailbox your team doesn't have to open | Bizzy-hosted | Both paths feed the same [unified inbox](/user-guide/email/inbox). You can mix: connect a personal Gmail for one sender and host `support@` through Bizzy for another. ## Prerequisites * **Bizzy-hosted:** you need a domain in **active** verified state. See [Domains → Verify](/user-guide/domains/verify) to add one. * **External:** your Google Workspace admin or Microsoft 365 admin may need to approve the app. No prep is required for personal Gmail. ## Next steps Create an address on a verified domain OAuth flow for Google and Microsoft # Creating an Email Template Source: https://docs.bizzyco.ai/user-guide/email-templates/creating Write a template with variables and validate it against Bizzy templating rules 1. Go to **Email Templates** in the sidebar. 2. Click **Add Email Template**. 3. Fill in the form. Create email template dialog ## Fields | Field | Limit | Required | | --------------- | --------------------- | -------- | | **Name** | 1 – 200 characters | Yes | | **Subject** | 1 – 1,000 characters | Yes | | **Body** | 1 – 50,000 characters | Yes | | **Description** | 0 – 2,000 characters | No | ## Template variables Use `{{mustache}}` syntax anywhere in the subject or body: ``` Subject: Welcome to {{business_name}}, {{first_name}}! Body: Hi {{first_name}}, Thanks for signing up — we're excited to have you. If you need help, just reply to this email. Cheers, {{sender_name}} ``` Bizzy extracts every `{{variable}}` automatically. There's no separate step to declare them — just use them where you want them filled in. ### What the preview shows The template detail page has a **Preview** tab that lists every extracted variable. You can fill sample values and see the rendered subject and body update live. The body preview shows the final delivered email — your content wrapped in the same standard layout Bizzy applies at send time. ## Validation Bizzy validates the subject and body for Mustache syntax errors on save — for example, an unclosed `{{` or a dangling `}}`. You cannot save a template whose syntax is invalid. Variables that aren't provided at send time render as empty strings — Mustache silently skips them. If a variable is truly required, enforce that in the automation or agent that calls the template, not in the template itself. ## Active vs. archived Every template has an **active** or **archived** state. Archived templates don't appear in the automation/agent picker but remain in the list for reference and reactivation. This is a soft state — archiving does not delete history. ## Next steps Preview, versions, sends Reference a template from an automation # Email Templates Source: https://docs.bizzyco.ai/user-guide/email-templates/index Reusable email templates with variables, previews, and version history Email templates are reusable, variable-aware message bodies. Write them once and let automations or agents fill them in with specific contact data at send time. Email templates list ## When to use templates * **Repeatable sends.** Welcome emails, follow-ups, appointment confirmations. * **Automations.** An automation references a template by ID — the template evolves independently of the automation logic. * **Agent sends.** Agents can use templates via LLM tools, so the message stays on-brand even when an agent writes it. ## What a template is * A **name** (internal label) * An optional **description** * A **subject** line * A **body** (plain text or markdown) * Optional **variables** in `{{mustache}}` syntax that get filled at send time Variables are not declared explicitly — Bizzy extracts them from whatever you put in the subject and body. ## Next steps Form fields, variables, validation Preview, version history, send via automation # Using Email Templates Source: https://docs.bizzyco.ai/user-guide/email-templates/using Preview, version history, and referencing templates from automations and agents The template detail page is where you iterate on an existing template. It has tabs for editing, previewing, and reviewing version history. Email template detail tabs ## Tabs | Tab | Contents | | ------------ | ------------------------------------------------------------------ | | **Settings** | Edit name, description, subject, body. Validation runs on save. | | **Preview** | Fill sample variable values and see the rendered email update live | | **History** | Version snapshots — view or restore any previous version | ## Previewing Open the **Preview** tab: 1. The list on the left shows every variable Bizzy extracted from the subject and body. 2. Type sample values for each. 3. The rendered subject and body update as you type. The preview shows the final delivered email: your rendered body wrapped in the same standard layout Bizzy applies when the email is sent. Unsafe HTML — scripts, event handlers, and embedded frames — is removed during rendering, and because the preview and the send path share the same renderer, the preview shows the exact sanitized document that is delivered. A plain-text alternative is also generated automatically at send time for email clients that prefer it. Use this to verify that your variable names match what your automations actually pass. ## Version history Every meaningful change to the subject or body creates a new version. The **History** tab shows: * When the version was saved * Who saved it * A **View** button to inspect that version * A **Restore** button to promote that version back to current Restoring a version becomes the new current version — older versions remain in history. ## Sending from an automation In an automation's instructions, reference the template by name or by ID. Under the hood, the automation calls `renderEmailTemplateContent` with the variable data it has available and the rendered result goes out via the configured sender. Because Mustache silently ignores missing variables, make sure the automation actually has the data it needs before the send step. ## Sending from an agent Agents can call a `send_email` tool that accepts a template reference and a map of variable values. Tool permissions apply — see [Tool permissions](/user-guide/agents/tool-permissions) — and a human can be required to approve each send. ## Deleting Use the dropdown on the list or detail page to **Delete** a template. Deletion is soft — the row is hidden but version history and references are preserved. ## Next steps Trigger a template send from an event Ask an agent to send using a template # Connecting Email Providers Source: https://docs.bizzyco.ai/user-guide/email/connect Link your Google or Microsoft email accounts to Bizzy Connect your email accounts to Bizzy to bring all your business communications into a single, unified inbox. Bizzy uses secure OAuth authentication to access your email—we never store your email password. ## Prerequisites * A Bizzy account with an active organization * Access to a Google Workspace/Gmail or Microsoft 365/Outlook account * Permission to authorize third-party applications (may require admin approval in some organizations) ## Connecting Google Workspace / Gmail To connect your Google account: 1. Navigate to **Settings > Connected Accounts** 2. Click **Connect Google** 3. Sign in to your Google account if prompted 4. Review the permissions Bizzy is requesting 5. Click **Allow** to authorize the connection Google OAuth authorization screen ### Google Permissions When connecting Google, Bizzy requests the following permissions: | Permission | Purpose | | ------------------------- | -------------------------------------- | | View your email messages | Read incoming and sent emails | | Send email on your behalf | Allow Bizzy to send replies | | View your contacts | Access contact information for context | | View your profile | Display your name and email in the app | Bizzy only accesses the permissions you grant. You can revoke access at any time from your Google Account settings or from Bizzy. ## Connecting Microsoft 365 / Outlook To connect your Microsoft account: 1. Navigate to **Settings > Connected Accounts** 2. Click **Connect Microsoft** 3. Sign in to your Microsoft account if prompted 4. Review the permissions Bizzy is requesting 5. Click **Accept** to authorize the connection Microsoft OAuth authorization screen ### Microsoft Permissions When connecting Microsoft, Bizzy requests the following permissions: | Permission | Purpose | | ----------------- | -------------------------------------- | | Read your mail | Access incoming and sent emails | | Send mail as you | Allow Bizzy to send replies | | Read your profile | Display your name and email in the app | For Microsoft 365 business accounts, your organization's admin may need to approve Bizzy as a trusted application before you can connect. ## Managing Connected Accounts Once connected, you can manage your email accounts from **Settings > Connected Accounts**: * **View permissions** - See which permissions are granted to each connection * **Manage** - Access connection-specific settings * **Disconnect** - Remove the connection and revoke Bizzy's access ## Multiple Accounts You can connect multiple email accounts to Bizzy. Each account will: * Appear in your unified inbox * Be identified by its email address in message lists * Maintain separate authentication and permissions ## Troubleshooting ### Connection Failed | Issue | Cause | Solution | | --------------------- | --------------------------------------------- | ---------------------------------------------- | | "Access Denied" error | Organization policy blocking third-party apps | Contact your IT administrator to approve Bizzy | | Connection times out | Network or browser issue | Try a different browser or clear cookies | | "Invalid Grant" error | Authorization expired | Disconnect and reconnect the account | ### Sync Issues | Issue | Cause | Solution | | ----------------------- | ----------------------------- | ------------------------------------------------- | | Emails not appearing | Initial sync in progress | Wait a few minutes for the first sync to complete | | Old emails missing | Only recent emails are synced | Bizzy syncs emails from the last 30 days | | Sent emails not showing | Permission issue | Verify the "send email" permission was granted | ### Organization Restrictions If you're using a corporate Google Workspace or Microsoft 365 account: 1. Check if your organization allows third-party applications 2. Contact your IT administrator if you see "admin approval required" 3. Request that Bizzy be added to the approved applications list ## Security Bizzy takes your email security seriously: * **OAuth 2.0** - We use industry-standard OAuth 2.0 for authentication * **No password storage** - We never see or store your email password * **Encrypted connections** - All data is transmitted over HTTPS * **Minimal permissions** - We only request permissions necessary for the features you use ## Next Steps Learn how to navigate your unified inbox Set up automated email workflows # Inbox Overview Source: https://docs.bizzyco.ai/user-guide/email/inbox Navigate and manage your unified inbox in Bizzy The Bizzy inbox brings every connected email account and SMS-enabled phone number into a single, organized view. This guide covers how to navigate, read, and manage your messages. Bizzy inbox interface ## Inbox modes Bizzy organizes messages into four modes, switched from the sidebar: | Mode | Contents | | ------------ | ------------------------------------------ | | **Inbox** | Incoming messages that need your attention | | **Snoozed** | Messages you've snoozed to review later | | **Archived** | Messages you've archived for reference | | **Sent** | Outgoing messages you've sent | Use the URL to link directly to a mode — `/{org}/inbox/snoozed`, `/{org}/inbox/archived`, etc. ## Reading messages ### The message list Each row shows: * **Sender** — who the message is from * **Subject** — the subject line (for email) or the SMS preview (for phone) * **Preview** — first line of the body * **Time** — when the message arrived * **Attachment icon** — present if the message has attachments Click a row (or focus it and press Enter/Space) to open the message in the reading pane. ### Thread view Email replies and forwards group into conversation threads: * All messages in the thread appear together, oldest at the top. * Thread participants are shown in the header. * Expand or collapse individual messages within the thread. ### Attachments Messages with attachments show an attachment icon in the list and the full file list inside the message view. Click an attachment to preview supported formats or download the original. ## Message actions Actions are available per message from the toolbar at the top of the reading pane. ### Archive Remove a message from your Inbox while keeping it accessible: 1. Open the message. 2. Click the **Archive** button. 3. The message moves to **Archived**. ### Snooze Hide a message and have it return later: 1. Open the message. 2. Click the **Snooze** button. 3. Pick how long from the dropdown: | Option | Returns to Inbox in | | ----------- | ------------------- | | For 1 hour | 1 hour | | For 3 hours | 3 hours | | For 1 day | 24 hours | | For 3 days | 72 hours | The message moves to **Snoozed** and comes back to **Inbox** when the time elapses. Custom times and "until next week"-style options are not currently exposed. ### Delete Permanently remove a message: 1. Open the message. 2. Click the **Delete** button. Delete is permanent. Use **Archive** if you might want the message back. ### Mark as read / unread Opening a message marks it read. To toggle state without opening, use the context menu on the message row. ## Selection and bulk actions The current UI supports **one selected message at a time**. Multi-select and bulk actions (select all, bulk archive, bulk delete) are not yet available — open an issue or contact support if you need them. ## Search Search is accessed via the search bar at the top of the inbox. It queries across every connected account and mode. ## Keyboard interactions The inbox relies on standard browser focus behavior plus a few specific actions: | Interaction | What it does | | ---------------------------------- | ----------------------------------------------- | | `Tab` / `Shift+Tab` | Move focus between message rows and UI controls | | `Enter` / `Space` on a focused row | Open that message | | Click | Open a message or activate a toolbar action | Per-action keyboard shortcuts (archive, snooze, delete) are not implemented today. ## Connected accounts and numbers When multiple mailboxes or phone numbers are in play: * Each message shows which account it arrived at. * Replies default to sending from the same address that received the original. * Sent messages are grouped under the outbound channel for easy auditing. ## Troubleshooting ### Messages not loading | Issue | Cause | Fix | | ---------------------------- | ------------------------ | ------------------------------------------------------------------- | | Empty inbox on first load | Initial sync in progress | Wait for sync to complete (usually a minute or two) | | Missing recent emails | Sync delay | Refresh the page | | "Connection error" indicator | Account was disconnected | Reconnect from [Email Addresses](/user-guide/email-addresses/index) | ### Performance | Issue | Cause | Fix | | ------------------- | ---------------- | ------------------------------- | | Slow list scroll | Very large inbox | Use search instead of scrolling | | Thread won't expand | Browser cache | Hard refresh (Cmd/Ctrl+Shift+R) | ## Next steps Add more sending addresses Auto-respond to incoming mail # Email Source: https://docs.bizzyco.ai/user-guide/email/index Manage your email communications with Bizzy Bizzy integrates with your existing email providers to bring all your business communications into a single, AI-powered inbox. Connect your Google or Microsoft accounts to start managing emails more efficiently. ## Features | Feature | Description | | --------------- | ---------------------------------------------------- | | Unified Inbox | View all emails from connected accounts in one place | | Thread View | See complete conversation threads with context | | Message Actions | Archive, snooze, and manage messages efficiently | | Search | Find messages quickly across all connected accounts | | AI Processing | Let Bizzy help process and respond to messages | ## Getting Started Link your Google or Microsoft email accounts Learn how to navigate and manage your inbox ## Supported Providers Bizzy currently supports the following email providers: * **Google Workspace / Gmail** - Full integration with Gmail, including labels and search * **Microsoft 365 / Outlook** - Complete support for Outlook and Exchange Online Additional email providers may be added in future updates. Contact support if you need integration with a specific provider. # Deleting Files and Folders Source: https://docs.bizzyco.ai/user-guide/files/deletion How Bizzy handles file and folder deletion Deletion in Bizzy Files is **soft** — deleted items are hidden from the UI but retained behind the scenes. Contact support if you need to restore something recently deleted. ## Deleting a file 1. Open the file (either in a row menu or from the detail page). 2. Click **Delete**. 3. Confirm. The file disappears from the list immediately (optimistic UI). If the delete request fails, the item reappears with an error message. ## Deleting a folder Folders can be deleted from their row menu. The folder and all its contents are soft-deleted together. Large folders may take a moment to finish processing after you click Delete. The folder disappears immediately from the UI, but downstream indexes (like agent retrieval) catch up asynchronously. ## What happens to agent indexes When a file with **agent access** is deleted, its chunks are removed from the retrieval index. Agents won't be able to retrieve content from deleted files in new queries. Existing agent conversations that previously cited the file still show the original content in their transcripts. ## Restoring There is no self-serve restore UI today. Contact support with the file name and approximate deletion time to recover deleted content. ## Next steps Back to Files Account-level storage and retention # Organizing Files with Folders Source: https://docs.bizzyco.ai/user-guide/files/folders Create nested folders and navigate them in Bizzy Files Folders keep your Files section organized. You can nest folders to any depth, and the breadcrumb at the top of the page shows where you are in the hierarchy. Folder breadcrumbs in Files ## Creating a folder 1. Navigate to the folder you want the new folder to live inside (or stay at the root). 2. Click **New Folder**. 3. Enter a name. 4. Save. The folder appears in the current view. Click into it to drill down. ## Navigating * **Click a folder** to drill in. * **Click a breadcrumb segment** to jump back to that level. * **Click the root** (leftmost breadcrumb) to return to the top of the hierarchy. ## Pagination Each folder page lists up to **50 items** (files + sub-folders) per page. Use the pagination controls to walk through larger folders. ## Deleting a folder Open the folder's menu and choose **Delete**. The folder and its contents are soft-deleted — see [Deletion](/user-guide/files/deletion). ## Next steps Add files into your folders Make folder contents agent-readable # Files Source: https://docs.bizzyco.ai/user-guide/files/index Upload, organize, and share files in Bizzy — with optional agent access for RAG-powered retrieval The Files section holds documents attached to your organization — contracts, manuals, reference docs, whatever agents or teammates need to read. Files can optionally be made accessible to [agents](/user-guide/agents/index), which indexes them for retrieval. Files list with folders and breadcrumbs ## What you can do Drag-drop or the upload dialog Nested folders with breadcrumb navigation Make files searchable by agents Soft-delete semantics ## Limits Storage is counted against your organization's allocation. See [Admin Guide → Billing](/admin-guide/billing/index) for current limits and overage behavior. # Agent Access & RAG Indexing Source: https://docs.bizzyco.ai/user-guide/files/rag-indexing Let Bizzy agents search and retrieve content from your uploaded files Files can optionally be made **agent-accessible**. When a file is agent-accessible, Bizzy indexes its contents for retrieval — so an [agent](/user-guide/agents/index) can pull relevant passages into its context when answering questions. ## The agent-access flag Every file has a boolean **agent access** flag: | State | What it means | | ------------------------------------------ | --------------------------------------------------- | | **Agent Access** (default off for privacy) | The file's contents can be retrieved by agents | | **No Agent Access** | The file exists in Files but is invisible to agents | The flag is set at upload time and shown as a badge on the file detail page. Agent access badge on file detail page ## How indexing works When you enable agent access: 1. Bizzy splits the file into semantic chunks using a **structural markdown chunker** — sections, paragraphs, and other structural boundaries rather than fixed-size windows. 2. Each chunk is embedded and stored in the retrieval index. 3. When an agent needs information, it queries the index and receives the most relevant chunks back as context. This approach (RAG — retrieval-augmented generation) keeps the agent grounded in your actual documents rather than relying on its generic training. There is no UI indicator for index status today. Once you enable agent access, give the system a minute to finish indexing before relying on the file's content in an agent chat. ## Turning agent access on or off Edit the file (via its detail page) and toggle **Agent access**. Turning it off removes the file from the index; turning it back on re-indexes. ## What content agents see Agents see the file's **text** — extracted from the document. Binary content (images, raw PDFs without OCR) isn't indexed meaningfully; the indexer works best with markdown, plain text, and documents with recoverable text layers. ## Privacy Agent-accessible files are scoped to your organization. Agents in other organizations never see them. Within your org, any agent that has the "read files" tool permission can retrieve content. ## Next steps Enable agent access at upload time Configure which agent reads which files # Uploading Files Source: https://docs.bizzyco.ai/user-guide/files/uploading Upload files to Bizzy via drag-drop or the upload dialog Files upload directly to Bizzy storage and appear in the list as soon as they finish. ## Two ways to upload ### Drag and drop Drop one or more files anywhere on the Files page. The upload starts immediately. ### Upload dialog Click **Upload Files** to open the upload dialog. Select one or more files from your file picker and confirm. File upload dialog ## What you can attach per file On upload you can optionally set: | Field | Purpose | | ---------------- | -------------------------------------------------------------------------------------- | | **Description** | Short note about what the file is | | **Tags** | Free-form labels | | **Agent access** | Whether agents can read this file — see [RAG indexing](/user-guide/files/rag-indexing) | ## Where uploads land New files appear in the **current folder** — whichever folder you're viewing when you start the upload. To upload into a specific folder, navigate into it first. ## Storage limits Before any upload, Bizzy checks your organization's remaining storage allocation. If you're out of space, the upload fails with an error and no partial file is stored. Raise your allocation in [Admin Guide → Billing](/admin-guide/billing/index). ## Troubleshooting | Problem | Likely cause | Fix | | --------------------------------- | --------------------------- | ------------------------------ | | Upload fails with "storage limit" | Hit your allocation | Free up space or upgrade | | Very large file times out | Network interruption | Retry from a stable connection | | File doesn't appear in list | Browser cached the old list | Refresh the page | ## Next steps Group files into folders Let agents search file contents # Frequently Asked Questions Source: https://docs.bizzyco.ai/user-guide/help/faq Quick answers to common questions about Bizzy accounts, billing, AI, and your data Short answers to the questions we hear most, with links to the pages that go deeper. ## Accounts & organizations Your **organization** is the workspace — it holds your team, data, and billing. A **business** is a commercial identity inside it, with its own profile, offerings, and Stripe connection; one organization can run several. See [Organizations](/get-started/concepts/organizations) and [Businesses](/get-started/concepts/businesses). Yes — invite members from your organization settings, up to your tier's seat limit; paid tiers can purchase additional seats. See [Managing Users](/admin-guide/organization/users). ## Billing & credits One credit equals one cent of overage. Inside your tier's allowance you never think about them — they only kick in when usage goes past what's included. See [Credits & Billing](/get-started/concepts/credits). You're warned at 90%, overage billing starts at 100% (paid tiers), and service pauses at 110% until you top up, upgrade, or the cycle resets. The Free tier pauses at 100%. See [Understanding Limits](/admin-guide/billing/limits). No. Credit balances carry over between billing periods. See [Credit Top-ups](/admin-guide/billing/credits). Nothing is deleted. Anything over the lower tier's caps is paused — newest first — and can be re-activated when you're back under the limit. See [Understanding Limits](/admin-guide/billing/limits). ## Email, domains & phone numbers Yes — connect a Google or Microsoft account via OAuth, or create an address on a domain you've verified with Bizzy. See [Connect Email](/user-guide/email/connect). Yes. Verify ownership of a domain you already have, or register a new one through Bizzy. See [Verify a Domain](/user-guide/domains/verify) and [Register a Domain](/user-guide/domains/register). Buy one through Bizzy — search by area code and capability, and check out in a couple of clicks. If you already have a Telnyx number you can attach it directly. See [Buying a Number](/user-guide/phone-numbers/buying). ## AI agents & your data Agents only see data inside your organization, and only the files you've explicitly given them access to — the **Agent access** flag is off by default. What agents can *do* is controlled per tool with allow/ask/deny permissions. See [Tool Permissions](/user-guide/agents/tool-permissions) and [RAG Indexing](/user-guide/files/rag-indexing). No — your data is not used to train foundation AI models. See the [AI disclosure](https://www.bizzyco.ai/ai-disclosure) for the full data-handling policy. Yes, per agent — every tier can use every available model, and usage is billed by the token. See [Agent Models](/user-guide/agents/models). Every chat is recorded as an agent conversation with the full transcript — tool calls, results, and approval decisions included. See [Transcripts](/user-guide/agent-conversations/transcripts). Automations are event-triggered rules that run on their own; agents are conversational and work with you across multiple turns. See [Agents](/get-started/concepts/agents) and [Automations](/get-started/concepts/automations). ## Developers Yes — a REST API at `api.bizzyco.ai/v1` with an OpenAPI spec, plus an MCP server so AI tools like Claude and Cursor can work with your data. See the [API Reference](/api-reference/introduction) and [MCP Server](/mcp-server/introduction). The REST API uses long-lived API keys you create and scope yourself; the MCP server uses OAuth with a consent screen where you pick the tool categories a client may use. See [API Keys](/admin-guide/security/api-keys) and [MCP Authentication](/mcp-server/authentication). ## More questions? The mental models behind Bizzy Ask us directly # Getting Support Source: https://docs.bizzyco.ai/user-guide/help/support How to contact the Bizzy team and what to include so we can help fast ## Before you contact us Three quick checks often save a round trip: * Scan [Troubleshooting](/user-guide/help/troubleshooting) for your symptom * Search these docs — the search bar covers every guide and reference page * Check [status.bizzyco.ai](https://status.bizzyco.ai) for ongoing incidents ## Contact support Email **[support@bizzyco.ai](mailto:support@bizzyco.ai)**. The same address handles general questions, billing issues, data-recovery requests (for example, restoring something you deleted), and security reports. ## What to include The more of this you include, the faster we can help: * Your **organization name** and the email you sign in with * The **feature or page** where the problem happens * **Steps to reproduce** — what you did, what you expected, what happened * **When it happened**, with your timezone * **Screenshots** of any error messages * For API issues: the **`X-Request-ID`** response header from the failing request — it pinpoints your exact request in our logs (see the [API introduction](/api-reference/introduction)) ## Reporting a security issue If you believe you've found a security vulnerability, email [support@bizzyco.ai](mailto:support@bizzyco.ai) with the details and we'll prioritize it. Please don't post suspected vulnerabilities publicly before we've had a chance to investigate. For how Bizzy protects your data, see [Data Protection](/admin-guide/security/data-protection). ## Service status [status.bizzyco.ai](https://status.bizzyco.ai) shows the live status of the platform — the app, API, MCP server, and messaging — plus incident history. Quick fixes for common issues Quick answers to common questions # Troubleshooting Source: https://docs.bizzyco.ai/user-guide/help/troubleshooting Fix the most common issues in Bizzy, with links to detailed guides Find the symptom below, try the quick fix, and follow the link for the full guide. If Bizzy itself seems down, check [status.bizzyco.ai](https://status.bizzyco.ai) before debugging your own setup. ## Email & inbox "Access denied" usually means your workspace blocks third-party apps — ask your IT administrator to approve Bizzy. An "invalid grant" error means the authorization expired: disconnect and reconnect the account. See [Connect Email → Troubleshooting](/user-guide/email/connect#troubleshooting). The initial sync can take a few minutes, and only emails from the last 30 days are synced. If a previously connected account stopped syncing, its token may have been revoked — reconnect it from the **Email Addresses** page. See [Connect Email → Troubleshooting](/user-guide/email/connect#troubleshooting). ## Domains & DNS TXT records can take 5–30 minutes to propagate, and the record must be at `_bizzy.` — not on the apex. See [Verify a Domain → Troubleshooting](/user-guide/domains/verify#troubleshooting). Sending reputation depends on your domain's authentication records being verified and warmed up. See [Deliverability](/user-guide/domains/deliverability). ## Phone numbers Your filters are probably too narrow or the area code is out of stock. Loosen the pattern, switch the type to **Any**, or try a nearby area code. See [Buying a Number → Troubleshooting](/user-guide/phone-numbers/buying#troubleshooting). Check the number's status on the **Phone Numbers** page — you'll also get a "Connection lost" notification when a number goes offline. See [Configuring Numbers](/user-guide/phone-numbers/configuring). ## Agents & automations The file's **Agent access** flag is probably off (it's off by default for privacy), or indexing hasn't finished — give it a minute after enabling. See [Agent Access & RAG Indexing](/user-guide/files/rag-indexing). Check that the automation is **Active** (not paused, completed, or expired) and that its trigger matches the event. See [Your First Automation → Troubleshooting](/user-guide/automations/first-automation#troubleshooting). You may have hit your monthly usage allowance — at the cutoff threshold, AI features pause until you buy credits, upgrade, or the billing cycle resets. Check **Settings > Account > Billing**. See [Understanding Limits](/admin-guide/billing/limits). ## API & MCP A `401` means the API key is missing or invalid; a `403` means the key lacks the permission scope for that endpoint. Check your key on the **API Keys** page. See [Error Handling](/api-reference/errors). You've exceeded your plan's per-minute request limit. Wait the number of seconds given by the `Retry-After` header, then retry. See [Rate Limits](/api-reference/rate-limits) for the limits on each plan. Re-run the OAuth flow from your client and approve the consent screen — and make sure the client points at `https://mcp.bizzyco.ai`. See [MCP Connection → Troubleshooting](/mcp-server/connection#troubleshooting). You've exceeded your plan's per-minute MCP request limit. The HTTP response looks normal — the throttle is reported inside the JSON-RPC error, so wait `data.retryAfter` seconds before retrying. See [MCP Rate Limits](/mcp-server/authentication#rate-limits) for the limits on each plan. ## Still stuck? For API issues, grab the `X-Request-ID` header from the failing response — it lets support find your exact request. See [Getting Support](/user-guide/help/support) for what else to include. Contact the team with the right details Check for ongoing incidents # User Guide Source: https://docs.bizzyco.ai/user-guide/index Learn how to use Bizzy to manage your business communications, contacts, tasks, and AI agents The User Guide covers the everyday features of Bizzy — the things you'll use to run your business. For account-level configuration (billing, team members, API keys, security), see the [Admin Guide](/admin-guide/organization/setup). New to Bizzy? Start with the [Setup Checklist](/user-guide/setup-checklist/index). It walks through the seven things worth doing first so the rest of the product works end-to-end. ## Get your inbox working Connect a mailbox or create an address on a verified domain Send and receive from addresses you control Buy phone numbers for voice and SMS Read, snooze, archive, and search unified messages ## Organize who and what People and companies you communicate with Customers synced from your Stripe account Track work with an urgency × importance matrix Upload documents for agents to reference ## Automate with AI Event-triggered workflows described in plain English Interactive AI assistants with tool permissions Review past agent transcripts and approvals Reusable templates with variables for sends ## Set up your business Profile, offerings, presences, Stripe Connect Verify or register domains for email History of phone numbers and other purchases Seven onboarding tasks to finish early ## Get help Quick fixes for the most common issues Quick answers about accounts, billing, and AI Contact the team with the right details Live platform status and incident history # Buying a Phone Number Source: https://docs.bizzyco.ai/user-guide/phone-numbers/buying Search available numbers from Telnyx and purchase through Bizzy Bizzy sells phone numbers through Telnyx. Checkout runs through Stripe — the line item appears on your Bizzy invoice, not a separate Telnyx one. ## Three entry points ### From the phone numbers inventory 1. Go to **Phone Numbers** in the sidebar. 2. Click **Buy number**. 3. You land on `/{org}/phone-numbers/buy`, the search page. ### From the purchases page 1. Go to **Purchases** in the sidebar. 2. Click **Purchase Phone Numbers** (or the **Phone Numbers** quick action). 3. You land on the same search page. ### From the inbox setup wizard If you're still setting up, the **Inbox Setup Wizard** at `/{org}/inbox/setup` lets you choose "Phone" and walks through location → search → select → checkout → success. ## The purchase flow 1. **Choose a location** — pick a country (default: United States) and optionally an area code. 2. **Refine your search** (optional) — narrow the results with any of these filters: * **Pattern** — a digit or vanity string up to 7 characters (e.g. `1000`, `COURIER`). Letters are mapped to phone-keypad digits before searching, so `COURIER` matches numbers containing `2687437`. * **Type** — restrict to **Local**, **Toll-free**, or **Mobile**, or leave as **Any**. * **Capabilities** — tick **Voice**, **SMS**, or **MMS** to require those features on the returned numbers. Voice and SMS are pre-selected; unchecking everything returns numbers regardless of capability. All filters live in the URL, so a search like `/{org}/phone-numbers/buy?countryCode=US&areaCode=415&pattern=1000&phoneNumberType=local&features=voice,sms` is shareable and bookmarkable. 3. **Pick a number** — Bizzy queries Telnyx and lists available numbers with their features and monthly cost. Click the one you want. 4. **Review** — confirm the selection and the calculated total on the purchase confirmation page. 5. **Checkout** — you're redirected to Stripe to pay. 6. **Success** — you land back on Bizzy's success page, and the number attaches to your organization automatically. The `phone_number_provision` metric is emitted for billing. ## Adding a number you already own If you already have a Telnyx number and want to attach it directly: 1. Go to **Phone Numbers**. 2. Click **Add existing number** to open the inline form (or visit `/{org}/phone-numbers/new` for the full-page version). 3. Fill in: * **Name** — a label you'll recognize * **Phone number** — in E.164 format (for example `+14155550123`) * **Country code** and **Region** * **Provider** — Telnyx 4. Save. The number is now available for configuration. ## Troubleshooting | Problem | Likely cause | Fix | | ---------------------------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | No available numbers in search | Filters too narrow, or area code out of stock at Telnyx | Loosen the pattern, switch type to **Any**, untick capabilities you don't strictly need, or try a nearby area code | | Vanity pattern returns nothing | The mapped digits don't exist in stock | Shorten the pattern (try 3–4 chars), or change the area code | | Stripe checkout fails | Payment method issue | Update in [Billing](/admin-guide/billing/index) | | Purchase succeeded but number not listed | Webhook lag | Wait 30–60 seconds and refresh | ## Next steps Turn on SMS, voice, voicemail, recording See your purchase history # Configuring a Phone Number Source: https://docs.bizzyco.ai/user-guide/phone-numbers/configuring Set SMS, voice, voicemail, and recording options on a Bizzy phone number Open any phone number from the Phone Numbers list to reach its detail page. Settings save when you submit the form. Phone number settings ## Channels Each number has three independent toggles: | Toggle | What it enables | | ------------- | ------------------------------------------------------------------------------------------------- | | **SMS** | Inbound and outbound text messaging. Incoming SMS lands in your [inbox](/user-guide/email/inbox). | | **Voice** | Inbound and outbound voice calls, governed by the voice mode below. | | **Voicemail** | Unanswered calls fall through to voicemail. | Leave channels off that you don't intend to use. ## Voice modes When **Voice** is on, choose how calls are handled: | Mode | Behavior | | ---------- | --------------------------------------------------------------- | | **WebRTC** | Calls ring into the Bizzy web app for you to answer in-browser | | **IVR** | An automated menu routes callers before (or instead of) a human | Additional modes may appear in the UI depending on what's rolled out for your account. ## Recording If recording is enabled on the number, both inbound and outbound calls are recorded. Recordings are retained per your account's retention settings — see [Admin Guide → Billing](/admin-guide/billing/index) for storage implications. Call recording laws vary by jurisdiction. In some regions you must notify or obtain consent from both parties. Check local requirements before enabling recording. ## Emergency address (E911) US local numbers must register an E911 emergency address before they can place outbound calls — open the number's **Emergency** tab to add and validate one. See [E911 Emergency Addresses](/admin-guide/compliance/e911) for the full registration flow, statuses, and troubleshooting. ## Name and display The **Name** field is how the number appears in the Bizzy UI — it's internal only. Outbound caller ID is set by Telnyx at the provider level. ## Removing a phone number Phone number removal releases the number back to Telnyx (or disconnects it if it's a BYO number). Contact support if you need to remove a number — the current UI does not expose self-serve deletion. ## Next steps Where inbound SMS and voice events land See what you've bought # Phone Numbers Source: https://docs.bizzyco.ai/user-guide/phone-numbers/index Buy and configure phone numbers in Bizzy for voice and SMS Bizzy provisions phone numbers through [Telnyx](https://telnyx.com). Once a number is attached to your organization, you can route calls, record voice, and send and receive SMS through the [inbox](/user-guide/email/inbox). Phone numbers list ## What you can do | Action | Where | | --------------------------------- | ---------------------------------------------------------------------------- | | Search for and buy a number | Inbox Setup Wizard → phone option, or Purchases → **Purchase Phone Numbers** | | Add a number you already own | **Phone Numbers** → **Add Phone Number** | | Configure SMS / voice / voicemail | Phone number detail page | | See purchase history | [Purchases](/user-guide/purchases/index) | ## Next steps Search Telnyx and check out via Stripe Voice mode, SMS, voicemail, recording # Purchases Source: https://docs.bizzyco.ai/user-guide/purchases/index History of phone-number purchases and other account-level buys in Bizzy The **Purchases** page is your record of what you've bought through Bizzy. Purchases dashboard ## What's tracked here | Product | Where to buy | | ------------- | ----------------------------------------------------------------- | | Phone numbers | Purchases → **Purchase Phone Numbers**, or the inbox setup wizard | **Domain registrations are not in Purchases.** Domains have their own flow on the [Domains](/user-guide/domains/register) page. This is intentional — Domains are account resources that persist and renew, while Purchases captures one-off buys of consumable or single-use items. For domain charge history and receipts, see [Domain Billing History](/user-guide/domains/billing). ## The purchase history list Each row shows: | Column | Notes | | ----------- | ---------------------------------------------- | | **Type** | The product line purchased | | **Date** | When you checked out | | **Items** | Phone numbers (or names) purchased | | **Amount** | Total charged in USD | | **Status** | `completed`, `processing`, `failed`, `pending` | | **Actions** | View details | ### Filters * **Search** — matches against item names / phone numbers * **Type** — filter to a specific product line ## Status banner The index shows a status banner when you land after a checkout: | URL param | Banner | | ------------- | ------------------------------------ | | `?success=1` | Success confirmation | | `?canceled=1` | You canceled checkout | | `?error=...` | Something went wrong during checkout | ## Making a purchase Click **Purchase Phone Numbers** to start the phone-number buy flow. See [Phone Numbers → Buying](/user-guide/phone-numbers/buying) for the full walkthrough. ## Next steps Current purchase flow Payment methods and invoices # Setup Checklist Source: https://docs.bizzyco.ai/user-guide/setup-checklist/index Seven onboarding tasks that unlock the rest of Bizzy The Setup Checklist is a home-page widget that tracks the seven things worth doing when you first join an organization. It auto-completes as you work — most tasks finish when you create the matching entity somewhere else in the product. Setup checklist widget on the home page ## The seven tasks | # | Task | What it asks you to do | Auto-completes when | | - | --------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------- | | 1 | **Business profile** | Fill in your business name, description, and industries | You save the [Business profile](/user-guide/businesses/profile) | | 2 | **Connect email** | Connect a Google or Microsoft account, or create an address on a verified domain | You add any [email address](/user-guide/email-addresses/index) | | 3 | **Add domain** | Verify ownership of a domain, or register one through Bizzy | You add a [domain](/user-guide/domains/index) | | 4 | **Connect phone** | Buy a phone number through Bizzy | You add a [phone number](/user-guide/phone-numbers/index) | | 5 | **Add contact** | Create your first contact record | You add a [contact](/user-guide/contacts/index) | | 6 | **Create automation** | Write a natural-language automation | You create an [automation](/user-guide/automations/index) | | 7 | **Invite team** | Send an invitation to a team member | You invite an [organization member](/admin-guide/organization/users) | ## How the widget behaves ### Open any task Tasks render as an accordion. The first pending task is expanded by default, showing its full description and a large **Open** button that takes you to the right page. Click any other row to expand it instead — only one task is open at a time. Collapsed pending tasks keep a quick **Open** link so you can jump straight to the right page without expanding them first. ### Completed tasks move to the bottom When you finish a task — by creating the matching entity or using **Mark done** — it moves to the bottom of the list with a check mark. Completed rows stay re-openable, so you can revisit the underlying page. There is no "Setup complete!" message: once every task is done, the widget disappears from the home page entirely. ### Manual actions (Owner and Admin only) If you have the **Owner** or **Admin** role, each pending task also shows a **Mark done** button that completes the task without creating the entity — useful when you finished it through another path (for example, you imported a contact via API before opening the web app). Users without the manage-setup-tasks permission see the same list but without this button — the tasks still auto-complete based on entity creation. Auto-completion runs regardless of your role. Even a regular user can finish the entire checklist just by using the product; the manual **Mark done** button only exists for Owner/Admin edge cases. ## When the widget appears * **At least one task pending:** the widget renders on the home page. * **All tasks completed:** the widget is hidden. The home page shows other dashboards (Eisenhower matrix, recent activity, etc.) in its place. * **Brand-new org with no tasks yet:** the widget renders with all seven tasks pending. ## Next steps Start with task 1 Work on task 2 # Eisenhower Widget Source: https://docs.bizzyco.ai/user-guide/tasks/eisenhower-widget The urgency × importance priority matrix on your Bizzy home page The Eisenhower widget is a 2×2 grid on your home page that groups active tasks by **urgency** and **importance**. It's the fastest way to see what to work on next. Home-page Eisenhower matrix ## The four quadrants | | High importance | Low importance | | ---------------- | ------------------------------------------------------------------ | ---------------------------------------------------------- | | **High urgency** | **Do** — top-left, crisis and deadlines | **Delegate** — top-right, interruptions and batchable work | | **Low urgency** | **Schedule** — bottom-left, strategic work worth planning time for | **Eliminate** — bottom-right, candidates to drop | A task's quadrant is purely a function of the importance and urgency fields you set on it. Change either field and the task moves accordingly. ## What the widget shows * Up to **50 tasks** across the four active statuses: `backlog`, `todo`, `in_progress`, `in_review`. * Each quadrant lists the tasks that fall into it, with title, status badge, and due date if one is set. * Clicking a task takes you to its detail page. ## Creating a task from the widget A **Create Task** button sits above the quadrants and opens the same form as the [Tasks page](/user-guide/tasks/managing), so you can add work without leaving the home page. A new task with an active status drops straight into its matching quadrant. When you have no tasks yet, the quadrants show empty-state hints — create your first task with the button and it appears immediately. ## Tips for the quadrants * Treat **Do** as a "today" list — if it stays crowded, importance or urgency probably needs re-evaluating. * Put recurring strategic work in **Schedule** and actually block calendar time for it. * **Delegate** is where to hand work off when that's an option. * If **Eliminate** keeps filling up, consider whether those tasks belong anywhere at all. ## Next steps Create and edit tasks Auto-create tasks from incoming email # Tasks Source: https://docs.bizzyco.ai/user-guide/tasks/index Track work in Bizzy with a priority matrix based on urgency and importance Tasks in Bizzy are lightweight to-do items that integrate with the rest of your workspace — they can be created manually, surfaced from emails by automations, or produced by agents while they work. Each task is scored on two axes — **urgency** and **importance** — which place it in one of four quadrants on the home-page Eisenhower matrix. Tasks list page ## The priority matrix The urgency × importance matrix sorts work by whether it needs your attention *now* and whether it moves the needle. | | High importance | Low importance | | ---------------- | ---------------------------------- | --------------------------------- | | **High urgency** | **Do** — do these first | **Delegate** — hand off or batch | | **Low urgency** | **Schedule** — plan time for these | **Eliminate** — consider dropping | Set urgency and importance when you create a task. Change them anytime as priorities shift. ## Task fields | Field | Required | Notes | | --------------- | -------- | ------------------------------------------------------------------------------------------- | | **Title** | Yes | Short summary — this is what shows in lists | | **Description** | No | Longer context | | **Status** | Yes | Defaults to `todo` — see [statuses](#statuses) | | **Importance** | Yes | Low, Medium, or High | | **Urgency** | Yes | Low, Medium, or High | | **Due date** | No | ISO date — no default | | **Category** | No | One of: Bug Fix, Documentation, Feature Request, Meeting, Other, Planning, Research, Review | ## Statuses Tasks move through six statuses: | Status | Meaning | | ------------- | --------------------------------- | | `backlog` | Captured but not worked yet | | `todo` | Ready to pick up | | `in_progress` | Actively being worked on | | `in_review` | Waiting on review or confirmation | | `done` | Completed | | `cancelled` | Won't be done | The home-page matrix widget shows tasks in the four active statuses (`backlog`, `todo`, `in_progress`, `in_review`). ## Next steps Create, edit, filter, and search tasks The home-page priority matrix # Managing Tasks Source: https://docs.bizzyco.ai/user-guide/tasks/managing Create, edit, filter, and search tasks in Bizzy This guide covers the task list, the create form, and the detail page. ## Creating a task 1. Click **Create Task** — the button is on the **Tasks** page and on the home page above the [Eisenhower widget](/user-guide/tasks/eisenhower-widget). Both open the same form. 2. Fill in the form: * **Title** (required) * **Description** (optional) * **Category** (optional) — Bug Fix, Documentation, Feature Request, Meeting, Other, Planning, Research, or Review * **Importance** — Low, Medium, or High * **Urgency** — Low, Medium, or High * **Due date** (optional) * **Status** — defaults to `todo` 3. Click **Save**. Create task modal The task appears in the list and — if its status is active — in the home-page [Eisenhower widget](/user-guide/tasks/eisenhower-widget). ## The task list The tasks index page is a data table with a filter sidebar. ### Filters | Filter | Behavior | | -------------- | -------------------------------------------------------------------------------- | | **Search** | Matches against both task title and description | | **Category** | Select one or more categories | | **Status** | Any subset of `backlog`, `todo`, `in_progress`, `in_review`, `done`, `cancelled` | | **Importance** | Any subset of Low, Medium, High | | **Urgency** | Any subset of Low, Medium, High | ### Sorting Sort by: * **Title** * **Due date** * **Created at** Each sort supports ascending or descending order. ## The task detail page Click any task to open its detail page. The page has three tabs: | Tab | Contents | | ------------ | ----------------------------------------------------------------------- | | **Overview** | Title, description, status, priority, due date, category — all editable | | **Activity** | Timeline of status changes, edits, and system events | | **Settings** | Delete the task | Changes saved on the Overview tab take effect immediately and are recorded in Activity. ## Deleting a task 1. Open the task. 2. Go to the **Settings** tab. 3. Click **Delete**. 4. Confirm. Deleted tasks are soft-deleted — they're hidden from the UI but the history remains. Contact support if you need to restore one. ## Next steps See tasks grouped by urgency × importance Have an automation create tasks from emails