Build Your First Integration

Before You Build

Complete these quick setup steps before using the Developer Portal.

1. Create your BOSS.Tech account

Create your account on app.boss.tech or download BOSS.Tech.

2. Create a company

Set up a company workspace inside BOSS.Tech. This is where everything you build will live.

3. Add a web path to create your web.boss.tech page

Only company owners (the person who created the company) can create the webpage.

Option 1 — In the mobile app

Select your company, open the hamburger menu in the top right, choose Edit Company, then select Create a Website. We auto-fill your company name, but you can customize it. Hit Next and you're ready to build.

Option 2 — In the Developer Portal

Sign in to dev.boss.tech, choose the correct company workspace in the top right, then go to Dashboard > Web Platform. Save or customize your web path, or connect a custom domain.

4. Log in to dev.boss.tech

Use the same account to access dev.boss.tech and start building.

Walkthrough: Building a QuickBooks Integration

This section walks you through a real integration setup step by step. Each screenshot shows exactly what you see in the Builder and what to do next.

Step 1 — Open the Builder

Go to dev.boss.tech and sign in. You land on the Builder home screen.

Step 2 — Navigate to BOSSi Integrations

Click Builder in the top nav. A dropdown shows all available modules.

Step 3 — Select an Integration

Click the "Select a integration" dropdown in the top left of the sidebar. A list of your existing integrations appears. Select quickbooks.

Once selected, the main panel loads the General Settings page for that integration.

Step 4 — Configure User Permissions

Click User Types in the left sidebar. This screen defines which user roles can trigger actions in this integration.

Step 5 — OAuth Setup: Basic Configuration

Click OAuth in the left sidebar. This is where you configure how companies authenticate with the external service. The Basic Configuration tab is selected by default.

Step 6 — OAuth Setup: Tokens and Webhook

Scroll down on the same OAuth page to see the token configuration and webhook settings.

Step 7 — OAuth Setup: Trigger Steps

Click the Trigger Steps tab at the top of the OAuth Setup page. This defines what happens immediately after a user successfully connects.

Step 8 — Schema: Basic Configuration

Click Schema in the left sidebar. The Basic Configuration tab shows the integration's identity, variables, and security settings.

Step 9 — Schema: Actions List

Click the Actions tab. This shows every operation the integration supports.

Step 10 — Action Configuration: quickbooks-sync-v1

Expand an action to see its configuration. Here is quickbooks-sync-v1 — the sync action that runs after OAuth and orchestrates the initial data pull.

Here is how the sync action calls child actions internally:

Step 11 — Action Configuration: invoices-post-v1

Now look at invoices-post-v1 — one of the child actions called by the sync. Notice the different flag configuration.

Step 12 — File Tree: Integration Structure

In the left sidebar, expand the quickbooks folder under the integration name. This shows the complete file structure of the integration.

Step 13 — File Tree: Inside the Action Folder

Expand the action/ folder to see all action subfolders. Each one corresponds to an action declared in schema.json.

Each action folder (e.g., bills-post-v1, bulk-fetch-files-v1, delete-integrations-v1) contains the code and configuration for that specific action.

Expand an individual action to see its internal structure:

Step 14 — Deploying and Merging

Once your code is ready, you have two operations available via the rocket icon and the three-dot menu:

Deploy (Rocket Icon)

Click the rocket icon next to any file or folder to deploy it to the current branch.

Merge (Three-Dot Menu)

Use Merge to promote changes from one branch to another (e.g., development to production).

Building with Vibe Code

Vibe Code is the AI-assisted development interface inside the Builder. You describe what you want in plain English, and the AI generates production-ready code by reading BOSSi's documentation and the external service's public API docs. No manual research needed.

How Vibe Code Works

Step 15 — Open Vibe Coding

Click Vibe Coding in the left sidebar. The Vibe Code interface opens with a prompt field asking "What are we building?"

Step 16 — Review the AI Response

After submitting your prompt, the AI returns complete code with explanations.

In this example, the prompt was: "create an OAuth file for Stripe with a hardcoded API key"

The AI generated:

{
  "name": "Stripe",
  "services": ["payments"],
  "isNonOauth": true,
  "tokens": {
    "apiKey": "sk_live_abc123..."
  },
  "genWebhook": true,
  "url": "{{self_url}}",
  "parameters": {
    "self_url": "{{generic_callback}}"
  },
  "requiredQueryParams": [],
  "triggerSteps": [
    {
      "action": "sync-payments-v1",
      "payload": { "full_sync": true }
    }
  ]
}

The AI also provided follow-up suggestions:

• If users need to supply their own Stripe key: use requiredQueryParams: ["apiKey"]
• If you need to handle Stripe events (e.g., payment_intent.succeeded): create a webhook.json

Step 17 — Debug: Testing Your Integration

Click Debug in the left sidebar. This is where you test actions and see real-time execution logs.

{
  "payload": {
    "name": "Hustle Plan",
    "description": "Monthly subscription plan",
    "sku": "HUSTLE-001",
    "type": "subscription",
    "isPublic": true,
    "imageUrl": "https://example.com/hustle.png",
    "productExternalId": "prod_stripe_123"
  }
}

Step 18 — Reading the Debug Logs

After clicking Run, the Log Events panel shows real-time execution results.

After clicking Run, the Log Events panel shows real-time execution results. See Step 19 below for detailed log examples.

Step 19 — Understanding Debug Logs

After clicking Run, the log events stream in real time. Here is a successful stripe-sync-v1 execution:

Expanding a Log Entry

Click the arrow on any log row to see the full detail. There are different types of log entries:

INFO Log (logging.info)

Shows your custom log messages with full context about the execution:

Trigger Log (send_to_trigger)

When your code calls send_to_trigger(), the debug panel shows the full payload being sent to the child action:

This is useful for verifying that the data being passed to child actions is correct. You can see the complete payload including all fields from the external service.

ERROR Log (logging.error)

When an action fails, the log shows a red 500 status code with the error details:

Using Logging in Your Code

Add logging statements to your action code to track execution and debug issues:

# INFO — track progress and print variables
logging.info(f"*-----------STARTING STRIPE SYNC for {resource.upper()}-----------*")
logging.info(f"Fetched {len(customers)} customers, total so far: {total}")

# ERROR — log failures with response details
logging.error(f"[ERROR] Failed to create product: {response.data.decode('utf-8')}")

# DEBUG — verbose details for troubleshooting
logging.debug(f"Raw API response: {data}")

Writing Actions with Vibe Code

Actions are the operations your integration performs. Each one is a Python script running in a managed sandbox — no packages to install, no servers to configure. Write, save, done.

How a Code Step Works

Every script defines a main(storage) function. Return a dict to pass data to the next step or back to the caller.

def main(storage):
    api_key = integration_variables["apiKey"]
    base_url = variables["baseUrl"]
    page = payload.get("page", 1)

    response = http.request(
        "GET",
        f"{base_url}/contacts?page={page}",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
    )

    if response.status == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        schedule_task(retry_after, retries=3)
        return {"error": f"Rate limited. Retry in {retry_after}s"}

    if response.status != 200:
        return {"error": f"API error: {response.status}"}

    data = json.loads(response.data.decode("utf-8"))
    contacts = data.get("contacts", [])

    if contacts:
        send_to_parser("sync-contacts-v1", contacts)

    if data.get("has_more"):
        send_to_trigger("sync-contacts-v1", {"page": page + 1})

    return {"synced": len(contacts)}

Key Functions You Will Use

Create Action (Push to External Service)

def main(storage):
    api_key = integration_variables["apiKey"]

    contact = {
        "first_name": payload.get("firstName"),
        "last_name": payload.get("lastName"),
        "email": payload.get("email"),
    }

    response = http.request(
        "POST", f"{variables['baseUrl']}/contacts",
        headers={
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json",
        },
        body=json.dumps(contact).encode("utf-8"),
    )

    if response.status not in (200, 201):
        return {"error": f"Failed: {response.status}"}

    created = json.loads(response.data.decode("utf-8"))
    return {"id": created["id"]}

Available Modules (No Imports Needed)

Configuration Reference

Detailed reference for each configuration file. Expand the sections you need.

{
  "name": "Northwind CRM",
  "services": ["contacts"],
  "isNonOauth": true,
  "genWebhook": true,
  "tokens": { "apiKey": "{{apiKey}}" },
  "url": "{{self_url}}",
  "parameters": { "self_url": "{{generic_callback}}" },
  "requiredQueryParams": ["apiKey"],
  "triggerSteps": [
    { "action": "sync-contacts-v1", "payload": { "full_sync": true } }
  ]
}

{
  "name": "Northwind CRM",
  "version": "1.0.0",
  "variables": { "baseUrl": "https://api.example.com/v1" },
  "actions": {
    "sync-contacts-v1": {
      "skipParser": false,
      "returnsData": true,
      "steps": [{ "codeRef": "action" }]
    }
  },
  "deleteAction": { "action": "delete-integrations-v1", "payload": {} }
}

{
  "validations": { "body_required": ["event_type"], "headers_required": [] },
  "triggerSteps": [{
    "condition": "'{{event_type}}' == 'contact.updated'",
    "memory": [{ "key": "cid", "value": "str(body['data']['id'])" }],
    "action": "sync-contacts-v1",
    "payload": { "contact_id": "{{cid}}" }
  }]
}

{
  "version": "1.0",
  "data": {
    "integrationPersonId": { "dataType": "string", "required": true, "equivalentName": "$.id" },
    "firstName": { "dataType": "string", "required": false, "equivalentName": "$.first_name" },
    "email": { "dataType": "string", "required": false, "equivalentName": "$.email" }
  }
}

{
  "owner": ["sync-contacts-v1", "delete-integrations-v1"],
  "admin": ["sync-contacts-v1"],
  "agent": ["sync-contacts-v1"],
  "contributor": []
}

FAQ

Can I import Python packages?

No. The sandbox blocks all imports. Everything you need is pre-loaded: http, json, datetime.datetime, logging, uuid, urlparse, b64().

How do I persist state between runs?

Use modify_tokens(). Always read integration_variables first, update the copy, then write back. It overwrites everything.

send_to_trigger vs send_to_parser?

send_to_trigger() queues a new action run (pagination, fan-out). send_to_parser() sends data through field mapping into BOSS.Tech storage.

How do I handle rate limits?

Check response.status == 429, then call schedule_task(seconds, retries=3). You can also set rate_limit on the action in schema.json.

How does OAuth token refresh work?

Define refreshTokenUrl in schema.json's security block. In code, just call get_token() — it refreshes automatically.

Where do logs go?

Use logging.info(), logging.error() in your code. Output shows in the Logs panel at dev.boss.tech.

What is deleteAction?

The action BOSS.Tech runs before removing an integration. Without it, webhooks you registered stay active forever after disconnect.