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

# Zapier Integration

> Connect BuildBetter with 7,000+ apps through Zapier automation

## What It Does

BuildBetter offers two ways to integrate with Zapier:

### 1. BuildBetter Zapier App (Pull Data from BuildBetter)

Use BuildBetter as a **trigger** in your Zaps to send call data to other apps when new calls or summaries are created.

**Available Triggers:**

* **New Call** - Triggers when a call is processed and ready
* **New Call Summary** - Triggers when a call summary is generated

**Available Searches:**

* **Get Call** - Fetch call details by ID
* **Get Call Summary** - Fetch full summary by call ID
* **Get Call Transcript** - Fetch complete transcript by call ID
* **Get Call Attendees** - Fetch list of attendees by call ID

### 2. Webhooks/API Integration (Push Data to BuildBetter)

Use Zapier's **Webhooks by Zapier** action to push feedback data into BuildBetter from other apps.

**Common Use Cases:**

* Send support tickets from Zendesk/Intercom to BuildBetter
* Push survey responses from Typeform/Google Forms
* Import customer feedback from Slack/Email
* Sync CRM notes and interactions

## Setup Instructions

### Option 1: Using BuildBetter Zapier App (Pull Data)

#### Prerequisites

* Active BuildBetter account
* Zapier account (free or paid)
* At least one processed call in BuildBetter

#### Connection Steps

1. **Create a Zap in Zapier**
   * Go to Zapier and click "Create Zap"
   * Search for "BuildBetter" in the trigger app

2. **Connect Your BuildBetter Account**
   * Select a trigger event (e.g., "New Call")
   * Click "Sign in to BuildBetter"
   * Authorize Zapier to access your BuildBetter data
   * Select your organization if prompted

3. **Test the Trigger**
   * Zapier will fetch recent calls to test the connection
   * Review the sample data
   * Click "Continue"

4. **Add Your Action**
   * Choose what app to send data to (e.g., Slack, Google Sheets, Notion)
   * Map BuildBetter fields to the action app
   * Test the action
   * Turn on your Zap

### Option 2: Push Data to BuildBetter (Using Webhooks)

To push data INTO BuildBetter, you'll use Zapier's "Webhooks by Zapier" action with BuildBetter's Feedback Ingestion API.

#### Prerequisites

* BuildBetter Organization API Key
* Feedback Source created in BuildBetter (see API Setup below)

#### API Setup in BuildBetter

Before creating Zaps, set up your API access:

1. **Get Your API Key**
   * Go to Settings → API in BuildBetter
   * Generate an Organization API Key
   * Copy and save it securely

2. **Create a Feedback Source** (One-time setup)

You can create a feedback source via the API or BuildBetter UI. Here's how via API:

```bash theme={null}
curl -X POST https://api.buildbetter.app/v3/rest/feedback-sources \
  -H "X-BuildBetter-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Zapier Support Tickets",
    "type": "api"
  }'
```

Save the returned `id` - you'll need it for your Zaps.

## Available Data from BuildBetter

When using BuildBetter as a trigger, you get access to:

### New Call Trigger

* **Call ID** - Unique identifier
* **Created At** - When the call was recorded
* **Name** - Call title (usually participants)
* **Short Summary** - AI-generated summary
* **Duration** - Length in seconds
* **URL** - Link to the call in BuildBetter
* **Tags** - All tags applied to the call

### New Call Summary Trigger

* **Summary ID** - Unique identifier
* **Call ID** - Associated call
* **Content** - Full summary markdown text
* **Created At** - When summary was generated

### Search Actions

Use these to fetch additional data in multi-step Zaps:

* **Get Call** - Fetch call metadata
* **Get Call Summary** - Fetch full summary content
* **Get Call Transcript** - Fetch complete transcript with speaker attribution
* **Get Call Attendees** - Fetch participant details (names, emails, IDs)

## Pushing Data to BuildBetter with Webhooks

Use Zapier's "Webhooks by Zapier" action to send data to BuildBetter's Feedback Ingestion API.

### Step-by-Step: Create Feedback from Any App

1. **Set Up Your Trigger**
   * Choose your source app (e.g., Typeform, Zendesk, Google Forms)
   * Select the trigger event (e.g., "New Response", "New Ticket")

2. **Add Webhooks by Zapier Action**
   * Click "+" to add an action
   * Search for "Webhooks by Zapier"
   * Select "POST" method

3. **Configure the Webhook**

   **URL:**

   ```
   https://api.buildbetter.app/v3/rest/feedback-sources/{FEEDBACK_SOURCE_ID}/records
   ```

   Replace `{FEEDBACK_SOURCE_ID}` with your feedback source ID

   **Headers:**

   ```
   X-BuildBetter-Api-Key: YOUR_API_KEY
   Content-Type: application/json
   ```

   **Data (as JSON):**
   See examples below for different use cases

4. **Test and Enable**
   * Test the webhook with sample data
   * Turn on your Zap

## Common Zapier Workflows

### Example 1: Typeform to BuildBetter

**Use Case:** Import NPS survey responses

**Trigger:** Typeform - New Entry
**Action:** Webhooks by Zapier - POST

**Webhook Configuration:**

**URL:**

```
https://api.buildbetter.app/v3/rest/feedback-sources/123/records
```

**Headers:**

```
X-BuildBetter-Api-Key: YOUR_API_KEY
Content-Type: application/json
```

**Data (JSON):**

```json theme={null}
{
  "display_ts": "{{zap_meta_human_now}}",
  "external_id": "typeform-{{response_id}}",
  "fields": [
    {
      "category": "identity",
      "type": "string",
      "name": "email",
      "value": "{{email}}"
    },
    {
      "category": "content",
      "type": "integer",
      "name": "nps_score",
      "value": "{{nps_score}}"
    },
    {
      "category": "content",
      "type": "string",
      "name": "feedback",
      "value": "{{feedback_text}}"
    },
    {
      "category": "metadata",
      "type": "string",
      "name": "survey_name",
      "value": "Q1 2025 NPS"
    }
  ]
}
```

<Note>
  Since we're using `email` in the identity field, BuildBetter will automatically find or create a person with that email.
</Note>

### Example 2: Zendesk Tickets to BuildBetter

**Use Case:** Import support tickets for analysis

**Trigger:** Zendesk - New Ticket
**Action 1:** Webhooks - PUT (Create/Update Person)
**Action 2:** Webhooks - POST (Send Feedback)

**Action 1 - Create Person:**

**URL:**

```
https://api.buildbetter.app/v3/rest/people
```

**Headers:**

```
X-BuildBetter-Api-Key: YOUR_API_KEY
Content-Type: application/json
```

**Data:**

```json theme={null}
{
  "first_name": "{{requester_first_name}}",
  "last_name": "{{requester_last_name}}",
  "email": "{{requester_email}}",
  "boundary": "external",
  "company": {
    "name": "{{organization_name}}",
    "domain": "{{organization_domain}}"
  }
}
```

**Action 2 - Send Ticket:**

**URL:**

```
https://api.buildbetter.app/v3/rest/feedback-sources/123/records
```

**Headers:**

```
X-BuildBetter-Api-Key: YOUR_API_KEY
Content-Type: application/json
```

**Data:**

```json theme={null}
{
  "person_id": "{{person_id}}",
  "display_ts": "{{created_at}}",
  "external_id": "zendesk-{{ticket_id}}",
  "fields": [
    {
      "category": "content",
      "type": "string",
      "name": "subject",
      "value": "{{subject}}"
    },
    {
      "category": "content",
      "type": "string",
      "name": "description",
      "value": "{{description}}"
    },
    {
      "category": "metadata",
      "type": "string",
      "name": "ticket_id",
      "value": "{{ticket_id}}"
    },
    {
      "category": "metadata",
      "type": "string",
      "name": "priority",
      "value": "{{priority}}"
    },
    {
      "category": "metadata",
      "type": "string",
      "name": "status",
      "value": "{{status}}"
    }
  ]
}
```

### Example 3: Google Forms to BuildBetter

**Use Case:** Import customer feedback surveys

**Trigger:** Google Forms - New Response
**Action:** Webhooks by Zapier - POST

**Webhook Configuration:**

**URL:**

```
https://api.buildbetter.app/v3/rest/feedback-sources/125/records
```

**Headers:**

```
X-BuildBetter-Api-Key: YOUR_API_KEY
Content-Type: application/json
```

**Data:**

```json theme={null}
{
  "display_ts": "{{timestamp}}",
  "external_id": "gform-{{response_id}}",
  "fields": [
    {
      "category": "identity",
      "type": "string",
      "name": "email",
      "value": "{{email_address}}"
    },
    {
      "category": "content",
      "type": "string",
      "name": "product_feedback",
      "value": "{{what_do_you_think_of_our_product}}"
    },
    {
      "category": "content",
      "type": "string",
      "name": "feature_request",
      "value": "{{what_features_would_you_like}}"
    },
    {
      "category": "metadata",
      "type": "string",
      "name": "source",
      "value": "Google Forms Feedback Survey"
    }
  ]
}
```

### Example 4: Slack Messages to BuildBetter

**Use Case:** Capture important Slack feedback manually

**Trigger:** Slack - New Saved Message (or New Reaction)
**Action:** Webhooks by Zapier - POST

**URL:**

```
https://api.buildbetter.app/v3/rest/feedback-sources/126/records
```

**Headers:**

```
X-BuildBetter-Api-Key: YOUR_API_KEY
Content-Type: application/json
```

**Data:**

```json theme={null}
{
  "display_ts": "{{timestamp}}",
  "external_id": "slack-{{channel_id}}-{{ts}}",
  "fields": [
    {
      "category": "identity",
      "type": "string",
      "name": "email",
      "value": "{{user_email}}"
    },
    {
      "category": "content",
      "type": "string",
      "name": "message",
      "value": "{{text}}"
    },
    {
      "category": "metadata",
      "type": "string",
      "name": "channel",
      "value": "{{channel_name}}"
    },
    {
      "category": "metadata",
      "type": "string",
      "name": "permalink",
      "value": "{{permalink}}"
    }
  ]
}
```

### Example 5: BuildBetter Call → Slack Notification

**Use Case:** Notify team when important calls are recorded

**Trigger:** BuildBetter - New Call
**Filter:** Only if tags contain "customer-feedback"
**Action:** Slack - Send Channel Message

**Slack Message:**

```
New customer feedback call recorded!

Title: {{name}}
Summary: {{short_summary}}
Duration: {{asset_duration_seconds}} seconds
Tags: {{tags__name}}

View call: {{url}}
```

## Understanding Feedback API Field Structure

When pushing data to BuildBetter, use this field structure:

### Field Categories

* **`identity`** - Used to match people (email, user\_id, etc.) - BuildBetter will auto-create person if needed
* **`content`** - The actual feedback content (comments, messages, responses)
* **`metadata`** - Additional context (priority, source, tags, channel, etc.)
* **`created_at`** - Timestamp fields
* **`identifier`** - External references (ticket IDs, response IDs)

### Field Types

* `string` - Text content
* `integer` - Whole numbers (NPS scores, ratings)
* `float` - Decimal numbers
* `boolean` - True/false
* `date` - Date only (YYYY-MM-DD)
* `datetime` - Full timestamp (ISO 8601)
* `json` - Structured data

### Person Matching

You have two options for matching people:

**Option 1: Use identity fields (simpler)**

```json theme={null}
{
  "fields": [
    {
      "category": "identity",
      "type": "string",
      "name": "email",
      "value": "customer@example.com"
    }
  ]
}
```

BuildBetter will automatically find or create a person with this email.

**Option 2: Create person first, then use person\_id**

```json theme={null}
{
  "person_id": 456,
  "fields": [...]
}
```

## Troubleshooting

### BuildBetter Zapier App Issues

**"Can't connect BuildBetter account"**

* Make sure you're logged into BuildBetter
* Verify you have at least one organization
* Check that you have admin access
* Try reconnecting in Zapier

**"No calls appearing in trigger test"**

* Ensure you have processed calls in BuildBetter
* Check that calls are in the selected organization
* Verify the trigger is set to the correct event type

**"Trigger not firing for new calls"**

* Zapier checks every 5-15 minutes depending on your plan
* New calls must be fully processed (transcript + summary complete)
* Check Zapier task history for errors

### Webhook/API Push Issues

**"401 Unauthorized"**

* Verify your API key is correct
* Check the header is `X-BuildBetter-Api-Key` (exact capitalization)
* Ensure the API key hasn't been revoked
* Regenerate the key if needed

**"404 Not Found"**

* Check that the feedback source ID exists
* Verify the URL is correct: `/v3/rest/feedback-sources/{id}/records`
* Make sure the feedback source wasn't deleted

**"400 Bad Request"**

* Verify JSON syntax is valid
* Check that all field types match (string, integer, etc.)
* Ensure required fields are present (display\_ts, fields array)
* Remove any null or undefined values

**"Person not being created"**

* Include email in an `identity` category field
* Or create person first with PUT /v3/rest/people
* Check that email format is valid

**"Duplicate records"**

* Use unique `external_id` for each record
* Format: `{source}-{unique-identifier}` (e.g., "typeform-12345")
* BuildBetter will skip duplicates with same external\_id

## Best Practices

### For Pulling Data from BuildBetter

**Use Filters**
Add Zapier filter steps to only process specific calls:

* Filter by tags (e.g., only "customer-feedback" calls)
* Filter by duration (e.g., calls longer than 10 minutes)
* Filter by participants (e.g., calls with external attendees)

**Combine Searches**
Use search actions to fetch additional data:

1. Trigger: New Call
2. Action: Get Call Transcript (to get full text)
3. Action: Get Call Attendees (to get participant emails)
4. Action: Send to destination app

### For Pushing Data to BuildBetter

**Use Consistent Field Names**

* Use snake\_case for field names
* Keep field names consistent across records
* Document your field schema for your team

**Include Metadata**
Add context fields to make feedback searchable:

* Source system (e.g., "zendesk", "typeform")
* Priority or urgency
* Product area or category
* Original URL or link

**Set Display Timestamp**
Always include `display_ts` with the original creation time:

```
"display_ts": "{{created_at}}"
```

Or use Zapier's timestamp: `"{{zap_meta_human_now}}"`

**Use External IDs**
Prevent duplicates with unique external IDs:

```
"external_id": "zendesk-ticket-{{ticket_id}}"
```

**Test with Sample Data**
Before turning on your Zap:

* Test with real sample data
* Verify records appear in BuildBetter
* Check that people are being created/matched correctly

## Example Zap Combinations

### Support Ticket Analysis

**Trigger:** Zendesk - New Ticket
**Action 1:** Webhooks - Create Person in BuildBetter
**Action 2:** Webhooks - Send Ticket to BuildBetter
**Action 3:** Slack - Notify team in #customer-feedback

### NPS Survey Tracking

**Trigger:** Typeform - New Entry
**Filter:** Only if NPS score \< 7 (detractors)
**Action 1:** Webhooks - Send to BuildBetter
**Action 2:** Slack - Alert customer success team

### Product Feedback Loop

**Trigger:** Google Forms - New Response
**Action 1:** Webhooks - Send to BuildBetter
**Action 2:** Notion - Create database entry
**Action 3:** Linear - Create issue (if critical feedback)

### Call Summary Distribution

**Trigger:** BuildBetter - New Call Summary
**Filter:** Only if tags contain "sales"
**Action 1:** Slack - Post to #sales-team
**Action 2:** Google Sheets - Add row to sales log
**Action 3:** HubSpot - Create note on contact

## Rate Limits

### BuildBetter Zapier App (Triggers)

* Polls every 5-15 minutes (depending on your Zapier plan)
* Returns up to 100 items per poll
* No additional rate limits

### Feedback Ingestion API (Webhooks)

* 100 requests per minute
* 1 record per request
* 10KB per field value limit

## Getting API Keys

**Organization API Key:**

1. Go to Settings → API in BuildBetter
2. Click "Generate API Key"
3. Copy and save securely
4. Use in `X-BuildBetter-Api-Key` header

**Scope:**

* Organization API keys have access to all data in your organization
* Keep them secure - don't expose in public repositories
* Rotate keys periodically for security

## Related Documentation

* [Feedback Ingestion API](/pages/api/feedback-ingestion) - Full API reference
* [GraphQL API](/pages/api/graphql-queries) - Query BuildBetter data directly
* [Webhooks](/pages/api/webhooks) - Real-time notifications from BuildBetter

## Support

Need help with Zapier integration?

* Check Zapier task history for error details
* Verify API key and feedback source ID
* Test API calls with curl before creating Zaps
* Contact BuildBetter support with your Zap configuration and error messages