# Zapier API documentation

SEA Survey provides a Zapier integration that allows you to automate workflows based on survey responses. When a customer submits a survey response, Zapier can automatically trigger actions in hundreds of other apps.

***

## Quick Start

{% stepper %}
{% step %}

### Open the Zapier app from the SEA Survey

Connect the Zapier app from the Integrations section in the sidebar
{% endstep %}

{% step %}

### Connect your account

Connect your account using your API key from the SEA Survey dashboard.
{% endstep %}

{% step %}

### Create a Zap

Create a Zap using the "New Response" trigger.
{% endstep %}

{% step %}

### Map response fields

Map response fields to your desired action app (e.g., Google Sheets, Slack, Email).
{% endstep %}

{% step %}

### Turn on your Zap

Turn on your Zap — it will fire automatically whenever a new survey response is submitted.
{% endstep %}
{% endstepper %}

### For detailed instructions

{% content-ref url="working-with-zapier" %}
[working-with-zapier](https://help.seacommerce.io/integration/working-with-zapier)
{% endcontent-ref %}

### Example Use Cases

* Google Sheets: Log every survey response to a spreadsheet for **analysis**
* Slack: Send a notification to a channel when a **negative response is received**
* Email: Send a follow-up email to customers who gave **low satisfaction scores**
* CRM: Create or update customer records with **survey feedback**
* Help Desk: Create a **support ticket** when a customer reports an issue

***

## Authentication

All API requests require an **API Key** passed via the `X-API-Key` header.

### Generating an API Key

{% stepper %}
{% step %}

### Open admin dashboard

Open your AG Survey admin dashboard.
{% endstep %}

{% step %}

### Navigate to Zapier integration

Go to Settings > Integrations > Zapier.
{% endstep %}

{% step %}

### Generate key

Click **Generate API Key**.
{% endstep %}

{% step %}

### Copy key

Copy the generated key — it will only be shown once.
{% endstep %}
{% endstepper %}

### Using the API Key

Include the API key in every request header:

```
X-API-Key: your_api_key_here
```

### Test Connection

Verify your API key is valid.

Endpoint:

```
GET /zapier/shop/status
```

Headers:

| Header      | Type   | Required | Description  |
| ----------- | ------ | -------- | ------------ |
| `X-API-Key` | string | Yes      | Your API key |

Response (200 OK):

```json
{
  "success": true,
  "data": {
    "shopId": "gid://shopify/Shop/123456",
    "shopName": "my-store",
    "authenticated": true
  },
  "message": "Connection successful"
}
```

Error Responses:

| Status | Body                                                  | Description                      |
| ------ | ----------------------------------------------------- | -------------------------------- |
| 401    | `{"success": false, "error": "API Key is required"}`  | Missing API key header           |
| 401    | `{"success": false, "error": "Invalid API Key"}`      | API key not found or deactivated |
| 500    | `{"success": false, "error": "Authentication error"}` | Internal server error            |

***

## Triggers

### New Response

Fires when a new survey response is submitted by a customer.

Type: REST Hook (real-time webhook)

When a Zap is turned on, Zapier subscribes a webhook URL. AG Survey sends a POST request to that URL every time a new response is received.

#### Trigger Output Fields

| Field                  | Type            | Description                                                                    |
| ---------------------- | --------------- | ------------------------------------------------------------------------------ |
| `id`                   | string          | Unique response ID                                                             |
| `surveyId`             | string          | Survey ID that the response belongs to                                         |
| `surveyTitle`          | string          | Name of the survey                                                             |
| `customerId`           | string          | Shopify customer ID                                                            |
| `customerEmail`        | string          | Customer email address                                                         |
| `customerName`         | string          | Customer display name                                                          |
| `answers`              | array           | List of question-answer pairs                                                  |
| `answers[].question`   | string          | The question text                                                              |
| `answers[].answer`     | string or array | The customer's answer. String for single-value answers, array for multi-select |
| `answers[].answerType` | string          | Answer type (see [Answer Types](#answer-types))                                |
| `createdAt`            | string          | ISO 8601 timestamp of when the response was submitted                          |
| `channelType`          | string          | How the survey was delivered (e.g., `email`, `popup`, `embedded`)              |

#### Example Trigger Payload

```json
{
  "id": "response_abc123",
  "surveyId": "survey_def456",
  "surveyTitle": "Post-Purchase Satisfaction",
  "customerId": "customer_789",
  "customerEmail": "jane@example.com",
  "customerName": "Jane Doe",
  "answers": [
    {
      "question": "How satisfied are you with your purchase?",
      "answer": "Very Satisfied",
      "answerType": "single"
    },
    {
      "question": "Which aspects did you like?",
      "answer": ["Product Quality", "Fast Shipping"],
      "answerType": "multiple"
    },
    {
      "question": "Rate your overall experience",
      "answer": "5",
      "answerType": "star_rating"
    },
    {
      "question": "Any additional feedback?",
      "answer": "Great experience, will buy again!",
      "answerType": "short_answer"
    }
  ],
  "createdAt": "2024-11-15T09:30:00.000Z",
  "channelType": "email"
}
```

#### Answer Types

| Type            | Description                | Answer Format                                                 |
| --------------- | -------------------------- | ------------------------------------------------------------- |
| `single`        | Single-choice question     | `string` — selected option                                    |
| `multiple`      | Multi-select question      | `array` — list of selected options                            |
| `star_rating`   | Star rating (1-5)          | `string` — numeric value (e.g., `"4"`)                        |
| `number_scale`  | Numeric scale (e.g., 1-10) | `string` — numeric value (e.g., `"7"`)                        |
| `satisfaction`  | Satisfaction level         | `string` — e.g., `"satisfied"`, `"neutral"`, `"dissatisfied"` |
| `short_answer`  | Free-text response         | `string` — user's text input                                  |
| `date`          | Date picker                | `string` — date value                                         |
| `consent_email` | Email consent checkbox     | `string` — `"true"` or `"false"`                              |

***

## Webhook API

These endpoints are used internally by Zapier to manage webhook subscriptions. They are documented here for reference and advanced use cases.

### Subscribe to Webhook

Register a webhook URL to receive new response events.

Endpoint:

```
POST /zapier/webhooks
```

Headers:

| Header         | Type   | Required | Description        |
| -------------- | ------ | -------- | ------------------ |
| `X-API-Key`    | string | Yes      | Your API key       |
| `Content-Type` | string | Yes      | `application/json` |

Request Body:

```json
{
  "targetUrl": "https://hooks.zapier.com/hooks/catch/12345/abcdef/",
  "event": "response.created"
}
```

| Field       | Type   | Required | Default            | Description                              |
| ----------- | ------ | -------- | ------------------ | ---------------------------------------- |
| `targetUrl` | string | Yes      | —                  | The URL to receive webhook POST requests |
| `event`     | string | No       | `response.created` | Event type to subscribe to               |

Response (200 OK):

```json
{
  "success": true,
  "data": {
    "id": "webhook_subscription_id"
  }
}
```

Error Responses:

| Status | Body                                                    | Description                |
| ------ | ------------------------------------------------------- | -------------------------- |
| 400    | `{"success": false, "error": "Target URL is required"}` | Missing targetUrl          |
| 401    | `{"success": false, "error": "Shop not identified"}`    | Invalid or missing API key |

> Note: If a subscription already exists for the same shop and target URL, it will be reactivated and the existing ID returned.

***

### Unsubscribe from Webhook

Remove a webhook subscription.

Endpoint:

```
DELETE /zapier/webhooks
```

Headers:

| Header         | Type   | Required | Description        |
| -------------- | ------ | -------- | ------------------ |
| `X-API-Key`    | string | Yes      | Your API key       |
| `Content-Type` | string | Yes      | `application/json` |

Request Body:

```json
{
  "targetUrl": "https://hooks.zapier.com/hooks/catch/12345/abcdef/"
}
```

| Field       | Type   | Required | Description                    |
| ----------- | ------ | -------- | ------------------------------ |
| `targetUrl` | string | Yes      | The webhook URL to unsubscribe |

Response (200 OK):

```json
{
  "success": true,
  "message": "Webhook unsubscribed successfully"
}
```

***

### Test Webhook

Send a sample payload to a webhook URL for testing.

Endpoint:

```
POST /zapier/webhooks/test
```

Headers:

| Header         | Type   | Required | Description        |
| -------------- | ------ | -------- | ------------------ |
| `X-API-Key`    | string | Yes      | Your API key       |
| `Content-Type` | string | Yes      | `application/json` |

Request Body:

```json
{
  "targetUrl": "https://hooks.zapier.com/hooks/catch/12345/abcdef/"
}
```

Response (200 OK):

```json
{
  "success": true,
  "message": "Test webhook sent successfully"
}
```

The test will send a sample response payload to the specified URL with dummy data.

***

### List Surveys (Polling Fallback)

Returns a list of surveys with sample response data. Used by Zapier as a polling fallback when webhooks are not available.

Endpoint:

```
GET /zapier/surveys
```

Headers:

| Header      | Type   | Required | Description  |
| ----------- | ------ | -------- | ------------ |
| `X-API-Key` | string | Yes      | Your API key |

Query Parameters:

| Parameter | Type    | Default | Description    |
| --------- | ------- | ------- | -------------- |
| `page`    | integer | `1`     | Page number    |
| `limit`   | integer | `10`    | Items per page |

Response (200 OK):

```json
{
  "success": true,
  "data": {
    "items": [
      {
        "surveyId": "survey_123",
        "surveyTitle": "Post-Purchase Feedback",
        "customerId": "sample_customer",
        "customerEmail": "sample@example.com",
        "customerName": "Sample Customer",
        "answers": [
          {
            "question": "How was your experience?",
            "answer": "Great",
            "answerType": "single"
          }
        ],
        "channelType": "email"
      }
    ],
    "total": 5,
    "hasNext": false,
    "hasPre": false
  }
}
```

***

## Supported Events

| Event              | Description                                             |
| ------------------ | ------------------------------------------------------- |
| `response.created` | Triggered when a customer submits a new survey response |

***

## Rate Limits

* Webhook delivery timeout: **10 seconds** per request
* Failed webhook deliveries are logged but not retried automatically
* API requests are subject to Firebase Cloud Functions quotas

***

## Error Handling

All error responses follow a consistent format:

```json
{
  "success": false,
  "error": "Human-readable error message"
}
```

### Common HTTP Status Codes

| Status | Meaning                                     |
| ------ | ------------------------------------------- |
| 200    | Success                                     |
| 400    | Bad request — missing or invalid parameters |
| 401    | Unauthorized — invalid or missing API key   |
| 500    | Internal server error                       |

***

## Base URL

```
https://sea-commerce-survey-app.firebaseapp.com
```

All endpoint paths in this documentation are relative to this base URL.

***

With the Zapier integration, SEA Survey enables you to turn customer feedback into automated actions across your existing tools. Whether you’re syncing responses to spreadsheets, notifying teams in real time, or creating records in your CRM, this integration **helps you act faster on customer insights**.

If you need more advanced workflows or custom integrations, feel free to reach out to our support team for further assistance.