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

# Zapier Integration API

> Learn how to connect BoothMaven with Zapier and use the integration API to automate workflows.

# BoothMaven - Zapier Integration API Documentation (OpenAPI 3.0)

> **Specification**: OpenAPI 3.0.3 / Zapier App v1.0.0\
> **Compliance**: [Zapier Platform Publishing Requirements - Section 5.2 (App APIs are documented)](https://docs.zapier.com/platform/publish/integration-publishing-requirements#5-2-app-apis-are-documented)\
> **Contact / Developer Support**: [support@boothmaven.com](mailto:support@boothmaven.com) • [BoothMaven.com](https://boothmaven.com)

***

## Overview

Official, comprehensive API documentation covering all endpoints for **BoothMaven's Zapier integration**.

BoothMaven captures leads, digital business cards, and event engagement data in real-time. This API enables seamless OAuth 2.0 authentication, REST Hook event streaming, sample polling, and lead creation between BoothMaven and 6,000+ apps on Zapier.

### Environment Base URLs

| Environment | Base URL | Description |
| :- | :- | :- |
| **Production** | `https://api.boothmaven.com` | Live production API |
| **Staging / Alpha** | `https://alpha-api.boothmaven.com` | Staging / testing API |

### General Conventions

* **Data Format**: `application/json` (except OAuth token exchange which uses `application/x-www-form-urlencoded`)
* **Authentication**: OAuth 2.0 Authorization Code Grant (`Authorization: Bearer <access_token>`)

***

## Table of Contents

1. [Authentication (OAuth 2.0)](#1-authentication-oauth-20)
   * [GET /oauth/authorize](#get-oauthauthorize)
   * [POST /oauth/token](#post-oauthtoken)
2. [Account & Connection Test](#2-account--connection-test)
   * [GET /api/zapier/me](#get-apizapierme)
3. [Trigger: New Contact (REST Hooks)](#3-trigger-new-contact-rest-hooks)
   * [POST /api/zapier/hooks/contacts/subscribe](#post-apizapierhookscontactssubscribe)
   * [DELETE /api/zapier/hooks/contacts/subscribe](#delete-apizapierhookscontactssubscribe)
   * [GET /api/zapier/contacts (Perform List / Sample Data)](#get-apizapiercontacts-perform-list--sample-data)
   * [Outbound Webhook Delivery (Payload)](#outbound-webhook-delivery-payload)
4. [Action: Create Contact](#4-action-create-contact)
   * [POST /api/zapier/contacts](#post-apizapiercontacts)
5. [Trigger: New Meeting (REST Hooks)](#5-trigger-new-meeting-rest-hooks)
   * [POST /api/zapier/hooks/meetings/subscribe](#51-subscribe-to-meeting-webhook)
   * [DELETE /api/zapier/hooks/meetings/subscribe](#52-unsubscribe-from-meeting-webhook)
   * [GET /api/zapier/meetings (Perform List / Sample Data)](#53-perform-list-sample-meetings)
   * [Outbound Webhook Delivery (Payload)](#54-webhook-event-delivery-payload)
6. [Action: Create Meeting](#6-action-create-meeting)
   * [POST /api/zapier/meetings](#post-apizapiermeetings)
7. [Error Handling & HTTP Status Codes](#7-error-handling--http-status-codes)
8. [OpenAPI 3.0.3 Specification (JSON)](#8-openapi-303-specification-json)

***

## 1. Authentication (OAuth 2.0)

BoothMaven uses industry-standard **OAuth 2.0 Authorization Code Grant** powered by Laravel Passport. Users authenticate via the BoothMaven consent screen, allowing Zapier to securely receive an authorization code and exchange it for a long-lived Bearer access token and refresh token.

### Scopes

| Scope | Description |
| :- | :- |
| `contacts:read` | Read access to captured contacts, leads, and event details. |

***

### `GET /oauth/authorize`

**User Authorization & Consent Screen**

Directs users to log in to BoothMaven and approve Zapier access. Once authorized, BoothMaven redirects back to Zapier's `redirect_uri` with an authorization `code` and the original `state` parameter.

#### Query Parameters

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `client_id` | `string` | **Yes** | OAuth 2.0 Client ID issued to the Zapier integration. |
| `redirect_uri` | `string (uri)` | **Yes** | Exact callback URL registered with BoothMaven (e.g. `https://zapier.com/dashboard/auth/oauth/return/App12345CLIAPI/`). |
| `response_type` | `string` | **Yes** | Must be set to `code`. |
| `scope` | `string` | No | Permissions requested. Supported scope: `contacts:read`. |
| `state` | `string` | No | Cryptographic state string generated by Zapier to prevent CSRF. |

#### Responses

* **`302 Found`**: Redirects to `redirect_uri?code=...&state=...` upon user authorization.
* **`400 Bad Request`**: Invalid client ID or redirect URI mismatch.

***

### `POST /oauth/token`

**Token Exchange & Refresh**

Exchanges an authorization code for an access token and refresh token, or issues a new access token when the current token expires.

#### Request Headers

```http theme={null}
POST /oauth/token HTTP/1.1
Host: api.boothmaven.com
Content-Type: application/x-www-form-urlencoded
Accept: application/json
```

#### Request Body Parameters (`application/x-www-form-urlencoded`)

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `grant_type` | `string` | **Yes** | `authorization_code` or `refresh_token`. |
| `client_id` | `string` | **Yes** | The OAuth Client ID. |
| `client_secret` | `string` | **Yes** | The OAuth Client Secret. |
| `redirect_uri` | `string (uri)` | Conditional | Required when `grant_type=authorization_code`. |
| `code` | `string` | Conditional | Required when `grant_type=authorization_code`. |
| `refresh_token` | `string` | Conditional | Required when `grant_type=refresh_token`. |

#### Example Request Body

```
grant_type=authorization_code&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&redirect_uri=YOUR_REDIRECT_URI&code=AUTHORIZATION_CODE
```

#### Response (`200 OK` - `application/json`)

```json theme={null}
{
  "token_type": "Bearer",
  "expires_in": 31536000,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9...",
  "refresh_token": "def502005a96..."
}
```

#### Error Responses

* **`400 Bad Request`**: Invalid grant, invalid credentials, or expired authorization code.
* **`401 Unauthorized`**: Client authentication failed.

***

## 2. Account & Connection Test

### `GET /api/zapier/me`

**Get Authenticated User Profile (Test Connection)**

Used by Zapier when a user connects their account to verify the OAuth token is valid and to construct dynamic connection labels such as `{{email}}` or `{{name}} ({{email}})` (e.g. `jane@example.com` or `Jane Doe (jane@example.com)`). Note: Zapier publishing rules require omitting the app name from the connection label.

#### Security

Requires Bearer token authentication:

```http theme={null}
GET /api/zapier/me HTTP/1.1
Host: api.boothmaven.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
```

#### Response (`200 OK` - `application/json`)

```json theme={null}
{
  "id": 42,
  "name": "Jane Doe",
  "username": "janedoe",
  "email": "jane@example.com"
}
```

#### Field Definitions

| Field | Type | Description |
| :- | :- | :- |
| `id` | `integer` | Unique user identifier in BoothMaven. |
| `name` | `string` | Full display name of the authenticated user. |
| `username` | `string` | BoothMaven login username. |
| `email` | `string` | Primary user email address. |

#### Error Responses

* **`401 Unauthorized`**: Missing, invalid, or expired Bearer token.

***

## 3. Trigger: New Contact (REST Hooks)

The **New Contact** trigger is implemented using Zapier REST Hooks. Zapier registers a subscription URL when the Zap is enabled. BoothMaven dispatches leads immediately when captured at events or digital cards.

***

### `POST /api/zapier/hooks/contacts/subscribe`

**Subscribe to New Contact Webhooks**

Called by Zapier when a Zap is turned **ON**. Subscribes the provided target URL to receive real-time contact events.

#### Security

* `Authorization: Bearer <access_token>`

#### Request Body (`application/json`)

```json theme={null}
{
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
}
```

> **Note**: Both `targetUrl` (camelCase) and `target_url` (snake\_case) are supported.

#### Response (`201 Created` - `application/json`)

```json theme={null}
{
  "id": 15,
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
}
```

#### Status Codes

* **`201 Created`**: Subscription created successfully.
* **`401 Unauthorized`**: Missing or invalid Bearer token.
* **`422 Unprocessable Entity`**: Missing or invalid `targetUrl`.

***

### `DELETE /api/zapier/hooks/contacts/subscribe`

**Unsubscribe from Webhooks**

Called by Zapier when a Zap is turned **OFF**, paused, or deleted. Removes the subscription so no further webhooks are dispatched.

#### Security

* `Authorization: Bearer <access_token>`

#### Request Body (`application/json`)

```json theme={null}
{
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "id": 15
}
```

> **Note**: Accepts either `id`, `targetUrl`, or `target_url`.

#### Response (`200 OK` - `application/json`)

```json theme={null}
{
  "success": true
}
```

#### Status Codes

* **`200 OK`**: Webhook subscription removed successfully.
* **`401 Unauthorized`**: Missing or invalid Bearer token.
* **`422 Unprocessable Entity`**: Neither `id` nor `targetUrl` provided.

***

### `GET /api/zapier/contacts` (Perform List / Sample Data)

**List Recent Contacts (Sample Data for Zap Editor)**

Called by Zapier during Zap configuration (when the user clicks "Test trigger"). Returns up to 20 of the user's most recent contacts with event context so users can map fields into downstream actions before live leads arrive.

#### Security

* `Authorization: Bearer <access_token>`

#### Response (`200 OK` - Array of Contacts)

```json theme={null}
[
  {
    "id": 1001,
    "first_name": "John",
    "last_name": "Smith",
    "email": "john.smith@example.com",
    "phone": "+64 21 123 4567",
    "company": "ABC Limited",
    "job_title": "Marketing Manager",
    "event_id": 25,
    "event_name": "BoothMaven Expo 2026",
    "created_at": "2026-09-14T10:30:00Z"
  }
]
```

***

### Outbound Webhook Delivery (Payload)

`POST {targetUrl}`

When a new contact is captured in BoothMaven (via live QR badge scanning, digital business card exchange, or event check-in), BoothMaven sends an HTTP `POST` request with this JSON payload directly to Zapier's registered `targetUrl`.

#### Delivered Webhook Payload

```json theme={null}
{
  "id": 1001,
  "first_name": "John",
  "last_name": "Smith",
  "email": "john.smith@example.com",
  "phone": "+64 21 123 4567",
  "company": "ABC Limited",
  "job_title": "Marketing Manager",
  "event_id": 25,
  "event_name": "BoothMaven Expo 2026",
  "created_at": "2026-09-14T10:30:00Z"
}
```

#### Contact Schema Fields

| Field | Type | Nullable | Description |
| :- | :- | :- | :- |
| `id` | `integer` | No | Unique BoothMaven contact record ID. |
| `first_name` | `string` | No | Contact's first name. |
| `last_name` | `string` | Yes | Contact's surname / last name. |
| `email` | `string (email)` | Yes | Primary email address. |
| `phone` | `string` | Yes | Mobile or office phone number. |
| `company` | `string` | Yes | Company or organization name. |
| `job_title` | `string` | Yes | Job designation or title. |
| `event_id` | `integer` | Yes | BoothMaven event identifier where lead was captured. |
| `event_name` | `string` | Yes | Associated event title. |
| `created_at` | `string (ISO 8601)` | No | Timestamp of contact capture in UTC. |

***

## 4. Action: Create Contact

Allows external applications (Google Sheets, CRM forms, Typeform, Webflow) to push contacts directly into the user's BoothMaven contact book.

### `POST /api/zapier/contacts`

**Create New Contact (Inbound Action)**

Creates a new contact record associated with the authenticated BoothMaven user.

#### Security

* `Authorization: Bearer <access_token>`

#### Request Body Schema (`application/json`)

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `first_name` | `string (max 255)` | **Yes** | Lead's first name. |
| `last_name` | `string (max 255)` | No | Lead's last name. |
| `email` | `string (email, max 255)` | No | Lead's email address. |
| `phone` | `string (max 50)` | No | Phone number. |
| `company` | `string (max 255)` | No | Company name. |
| `job_title` | `string (max 255)` | No | Designation or job title. |

#### Sample Request Body

```json theme={null}
{
  "first_name": "Alice",
  "last_name": "Williams",
  "email": "alice.williams@example.com",
  "phone": "+1 555 234 5678",
  "company": "Tech Innovators Inc",
  "job_title": "Senior Solutions Architect"
}
```

#### Response (`201 Created` - `application/json`)

```json theme={null}
{
  "id": 1002,
  "first_name": "Alice",
  "last_name": "Williams",
  "email": "alice.williams@example.com",
  "phone": "+1 555 234 5678",
  "company": "Tech Innovators Inc",
  "job_title": "Senior Solutions Architect",
  "event_id": null,
  "event_name": null,
  "created_at": "2026-09-16T12:45:00Z"
}
```

#### Error Responses

* **`401 Unauthorized`**: Missing or invalid Bearer token.
* **`422 Unprocessable Entity`**: Missing required fields (`first_name`) or invalid data format.

***

## 5. Trigger: New Meeting (REST Hooks)

The **New Meeting** trigger uses Zapier REST Hooks. When a user turns on a Zap in Zapier, Zapier registers a subscription URL with BoothMaven. When a meeting is scheduled in BoothMaven (via web, mobile, public booking link, or API), BoothMaven delivers the meeting payload to all subscribed URLs in real-time.

### 5.1 Subscribe to Meeting Webhook

#### Request

* **Method**: `POST`
* **URL**: `/api/zapier/hooks/meetings/subscribe`
* **Headers**:
  * `Authorization: Bearer <access_token>`
  * `Content-Type: application/json`
  * `Accept: application/json`
* **Body**:

```json theme={null}
{
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
}
```

#### Response (`201 Created`)

```json theme={null}
{
  "id": 19,
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
  "target_url": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
}
```

***

### 5.2 Unsubscribe from Meeting Webhook

Called by Zapier when a Zap is turned off or deleted.

#### Request

* **Method**: `DELETE`
* **URL**: `/api/zapier/hooks/meetings/subscribe`
* **Headers**:
  * `Authorization: Bearer <access_token>`
  * `Content-Type: application/json`
  * `Accept: application/json`
* **Body**:

```json theme={null}
{
  "id": 19,
  "targetUrl": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
}
```

#### Response (`200 OK`)

```json theme={null}
{
  "success": true
}
```

***

### 5.3 Perform List (Sample Meetings)

Called by Zapier in the Zap Editor to fetch real sample records for field mapping before live webhooks are sent. Returns up to 20 of the authenticated user's most recent meetings.

#### Request

* **Method**: `GET`
* **URL**: `/api/zapier/meetings`
* **Headers**:
  * `Authorization: Bearer <access_token>`
  * `Accept: application/json`

#### Response (`200 OK`)

```json theme={null}
[
  {
    "id": 5001,
    "meeting_name": "Quarterly Product Demo",
    "meeting_status": "scheduled",
    "meeting_format": "virtual",
    "priority": "high",
    "meeting_date": "2026-10-15",
    "meeting_time": "14:30:00",
    "meeting_duration": 45,
    "timezone": "America/New_York",
    "meeting_location": "https://meet.google.com/abc-def-ghi",
    "meeting_agenda": "Review enterprise features and answer questions",
    "meeting_url": "https://view.boothmaven.com/cards/meeting/abcdef123456",
    "booking_source": "zapier",
    "event_id": 25,
    "event_name": "BoothMaven Expo 2026",
    "primary_contact_id": 1001,
    "primary_contact_name": "Ada Lovelace",
    "primary_contact_email": "ada@example.com",
    "contacts": [
      {
        "id": 1001,
        "name": "Ada Lovelace",
        "email": "ada@example.com",
        "phone": "+1234567890",
        "company": "Analytical Engines Ltd"
      }
    ],
    "created_at": "2026-09-23T10:00:00Z"
  }
]
```

***

### 5.4 Webhook Event Delivery (Payload)

When a meeting is scheduled in BoothMaven, BoothMaven sends an HTTP `POST` to Zapier's subscribed `targetUrl`:

#### Payload Structure

```json theme={null}
{
  "id": 5001,
  "meeting_name": "Quarterly Product Demo",
  "meeting_status": "scheduled",
  "meeting_format": "virtual",
  "priority": "high",
  "meeting_date": "2026-10-15",
  "meeting_time": "14:30:00",
  "meeting_duration": 45,
  "timezone": "America/New_York",
  "meeting_location": "https://meet.google.com/abc-def-ghi",
  "meeting_agenda": "Review enterprise features and answer questions",
  "meeting_url": "https://view.boothmaven.com/cards/meeting/abcdef123456",
  "booking_source": "zapier",
  "event_id": 25,
  "event_name": "BoothMaven Expo 2026",
  "primary_contact_id": 1001,
  "primary_contact_name": "Ada Lovelace",
  "primary_contact_email": "ada@example.com",
  "contacts": [
    {
      "id": 1001,
      "name": "Ada Lovelace",
      "email": "ada@example.com",
      "phone": "+1234567890",
      "company": "Analytical Engines Ltd"
    }
  ],
  "created_at": "2026-09-23T10:00:00Z"
}
```

***

## 6. Action: Create Meeting

Allows external applications (Google Calendar, Calendly, Typeform, Webforms, CRMs) to schedule meetings directly in BoothMaven.

### `POST /api/zapier/meetings`

#### Security

* `Authorization: Bearer <access_token>`

#### Request Body Schema (`application/json`)

| Field | Type | Required | Description |
| :- | :- | :- | :- |
| `meeting_name` | `string (max 191)` | **Yes** | Title or name of the meeting |
| `meeting_date` | `string (date)` | **Yes** | Meeting date (`YYYY-MM-DD`) |
| `meeting_time` | `string` | **Yes** | Meeting time (`HH:MM` or `HH:MM:SS`) |
| `meeting_duration` | `integer` | No | Duration in minutes (default `30`) |
| `meeting_format` | `string` | No | Format (`virtual`, `hybrid`, `inPerson`) |
| `priority` | `string` | No | Priority level (`high`, `medium`, `low`) |
| `meeting_location` | `string` | No | Physical address or video conference URL |
| `meeting_agenda` | `string` | No | Meeting description or notes |
| `timezone` | `string` | No | Timezone identifier (e.g. `America/New_York`) |
| `event_id` | `integer` | No | Linked BoothMaven event ID |
| `contact_id` | `integer \| integer[]` | No | Existing contact ID(s) to invite |
| `contact_email` | `string (email)` | No | Email of existing contact to link if ID is unknown |

#### Sample Request Body

```json theme={null}
{
  "meeting_name": "Enterprise Demo Call",
  "meeting_date": "2026-11-01",
  "meeting_time": "14:00:00",
  "meeting_duration": 45,
  "meeting_format": "virtual",
  "meeting_location": "https://meet.google.com/xyz",
  "meeting_agenda": "Review enterprise features and answer questions",
  "contact_email": "lead@example.com"
}
```

#### Response (`201 Created`)

```json theme={null}
{
  "id": 5002,
  "meeting_name": "Enterprise Demo Call",
  "meeting_status": "scheduled",
  "meeting_format": "virtual",
  "priority": null,
  "meeting_date": "2026-11-01",
  "meeting_time": "14:00:00",
  "meeting_duration": 45,
  "timezone": "UTC",
  "meeting_location": "https://meet.google.com/xyz",
  "meeting_agenda": "Review enterprise features and answer questions",
  "meeting_url": "https://view.boothmaven.com/cards/meeting/xyz987",
  "booking_source": "zapier",
  "event_id": null,
  "event_name": null,
  "primary_contact_id": 1001,
  "primary_contact_name": "Lead Person",
  "primary_contact_email": "lead@example.com",
  "contacts": [
    {
      "id": 1001,
      "name": "Lead Person",
      "email": "lead@example.com",
      "phone": "+1234567890",
      "company": "Acme Inc"
    }
  ],
  "created_at": "2026-09-23T10:15:00Z"
}
```

***

## 7. Error Handling & HTTP Status Codes

BoothMaven API uses standard HTTP response status codes. Errors include a JSON body detailing the failure cause.

| Status Code | Reason | Description |
| :- | :- | :- |
| **`200 OK`** | Success | Request succeeded. |
| **`201 Created`** | Created | Resource or webhook subscription created successfully. |
| **`400 Bad Request`** | Invalid Request | Malformed request syntax or invalid OAuth parameters. |
| **`401 Unauthorized`** | Authentication Required | Missing, invalid, or expired Bearer token in the `Authorization` header. |
| **`422 Unprocessable Entity`** | Validation Error | Input validation failed (missing required field or invalid format). |
| **`500 Internal Server Error`** | Server Error | An unexpected server error occurred. |

### Sample Validation Error (`422 Unprocessable Entity`)

```json theme={null}
{
  "message": "The targetUrl or target_url field is required and must be a valid URL.",
  "errors": {
    "targetUrl": ["A valid target URL is required."]
  }
}
```

### Sample Unauthorized Error (`401 Unauthorized`)

```json theme={null}
{
  "message": "Unauthenticated."
}
```

***

## 8. OpenAPI 3.0.3 Specification (JSON)

Below is the complete, machine-readable OpenAPI 3.0.3 specification in JSON:

```json theme={null}
{
  "openapi": "3.0.3",
  "info": {
    "title": "BoothMaven Zapier Integration API",
    "version": "1.0.0",
    "description": "Comprehensive API documentation for BoothMaven's Zapier integration. BoothMaven is an event engagement, lead capture, and digital business card platform. This API enables seamless synchronization of contacts captured during live events and meetings with external CRMs, spreadsheets, and marketing automation tools via Zapier.\n\n### Authentication\nAuthentication is powered by **OAuth 2.0 Authorization Code Grant** (Laravel Passport). All API requests must include a valid Bearer token in the `Authorization` header.\n\n### Base URLs\n* **Production**: `https://api.boothmaven.com`\n* **Staging / Testing**: `https://alpha-api.boothmaven.com`\n\n### Support & Inquiries\nFor integration support or developer inquiries, contact [support@boothmaven.com](mailto:support@boothmaven.com).",
    "contact": {
      "name": "BoothMaven Developer Support",
      "url": "https://boothmaven.com",
      "email": "support@boothmaven.com"
    }
  },
  "servers": [
    {
      "url": "https://api.boothmaven.com",
      "description": "Production Server"
    },
    {
      "url": "https://alpha-api.boothmaven.com",
      "description": "Staging / Alpha Server"
    }
  ],
  "tags": [
    {
      "name": "Authentication (OAuth 2.0)",
      "description": "OAuth 2.0 Authorization Code grant and token exchange endpoints."
    },
    {
      "name": "Account",
      "description": "Identity verification and connection testing."
    },
    {
      "name": "Trigger: New Contact (REST Hooks)",
      "description": "Webhook subscriptions and sample contact polling for real-time lead sync."
    },
    {
      "name": "Action: Create Contact",
      "description": "Inbound endpoint to create new contacts in BoothMaven from third-party apps."
    },
    {
      "name": "Trigger: New Meeting (REST Hooks)",
      "description": "Webhook subscriptions and sample meeting polling for real-time meeting sync."
    },
    {
      "name": "Action: Create Meeting",
      "description": "Inbound endpoint to schedule new meetings in BoothMaven from external calendars and scheduling tools."
    }
  ],
  "paths": {
    "/oauth/authorize": {
      "get": {
        "tags": ["Authentication (OAuth 2.0)"],
        "summary": "Request Authorization Code",
        "description": "Initiates the standard OAuth 2.0 authorization code flow. Directs users to the BoothMaven login and consent screen where they grant permission to access their BoothMaven contacts.",
        "parameters": [
          {
            "name": "client_id",
            "in": "query",
            "required": true,
            "description": "OAuth 2.0 Client ID issued to the Zapier application.",
            "schema": {
              "type": "string",
              "example": "9a123456-7890-abcd-ef01-234567890abc"
            }
          },
          {
            "name": "redirect_uri",
            "in": "query",
            "required": true,
            "description": "The exact callback URL registered with BoothMaven (e.g. `https://zapier.com/dashboard/auth/oauth/return/App12345CLIAPI/`).",
            "schema": {
              "type": "string",
              "format": "uri",
              "example": "https://zapier.com/dashboard/auth/oauth/return/App12345CLIAPI/"
            }
          },
          {
            "name": "response_type",
            "in": "query",
            "required": true,
            "description": "Must be set to `code`.",
            "schema": {
              "type": "string",
              "default": "code",
              "enum": ["code"]
            }
          },
          {
            "name": "scope",
            "in": "query",
            "required": false,
            "description": "Permissions requested. Supported scope: `contacts:read`.",
            "schema": {
              "type": "string",
              "default": "contacts:read",
              "example": "contacts:read"
            }
          },
          {
            "name": "state",
            "in": "query",
            "required": false,
            "description": "Unique cryptographic state parameter to prevent CSRF attacks.",
            "schema": {
              "type": "string",
              "example": "d98f7e2c-b51a-4c28-98e3-0d5b47a6cf81"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirects to login page if unauthenticated, or redirects to `redirect_uri` with `code` and `state` upon user authorization."
          },
          "400": {
            "description": "Bad Request - Invalid client ID or redirect URI mismatch.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/oauth/token": {
      "post": {
        "tags": ["Authentication (OAuth 2.0)"],
        "summary": "Exchange Authorization Code / Refresh Access Token",
        "description": "Exchanges an authorization code for an access token and refresh token, or refreshes an expired access token using a refresh token.",
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "$ref": "#/components/schemas/TokenRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Token issued successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid grant, invalid credentials, or expired authorization code.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Client authentication failed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/zapier/me": {
      "get": {
        "tags": ["Account"],
        "summary": "Get Authenticated User Profile (Connection Test)",
        "description": "Returns the authenticated user's profile information. Used by Zapier during initial account connection testing and to display dynamic connection labels (e.g. `jane@example.com` or `Jane Doe (jane@example.com)` without app name per Zapier publishing conventions).",
        "security": [{ "bearerAuth": [] }, { "oauth2": ["contacts:read"] }],
        "responses": {
          "200": {
            "description": "Authenticated user profile.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/User"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing, invalid, or expired Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/zapier/hooks/contacts/subscribe": {
      "post": {
        "tags": ["Trigger: New Contact (REST Hooks)"],
        "summary": "Subscribe to New Contact Webhook",
        "description": "Registers a REST hook subscription for the authenticated user. When a Zap containing the **New Contact** trigger is activated in Zapier, Zapier calls this endpoint with a unique webhook target URL. When a contact is captured in BoothMaven, a webhook event is dispatched to this target URL.",
        "security": [{ "bearerAuth": [] }, { "oauth2": ["contacts:read"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscribeInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook subscription created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscribeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error - Missing or invalid targetUrl.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          }
        },
        "callbacks": {
          "onNewContact": {
            "{$request.body#/targetUrl}": {
              "post": {
                "summary": "Outbound Webhook Delivery: New Contact Captured",
                "description": "When a new contact is captured in BoothMaven, BoothMaven delivers this HTTP POST payload to the registered Zapier `targetUrl` in near real-time.",
                "requestBody": {
                  "required": true,
                  "content": {
                    "application/json": {
                      "schema": {
                        "$ref": "#/components/schemas/Contact"
                      }
                    }
                  }
                },
                "responses": {
                  "200": {
                    "description": "Zapier acknowledges receipt of the webhook event."
                  }
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Trigger: New Contact (REST Hooks)"],
        "summary": "Unsubscribe from New Contact Webhook",
        "description": "Deactivates and removes an existing webhook subscription for the authenticated user. Called automatically by Zapier when a Zap is turned off, paused, or deleted.",
        "security": [{ "bearerAuth": [] }, { "oauth2": ["contacts:read"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UnsubscribeInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook subscription removed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnsubscribeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error - Neither `id` nor `targetUrl` provided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/zapier/contacts": {
      "get": {
        "tags": ["Trigger: New Contact (REST Hooks)"],
        "summary": "List Recent Contacts (Perform List / Sample Data)",
        "description": "Retrieves up to 20 of the most recently created contacts for the authenticated user, including linked event details. Used by the Zap Editor to display real sample data for field mapping during Zap creation.",
        "security": [{ "bearerAuth": [] }, { "oauth2": ["contacts:read"] }],
        "responses": {
          "200": {
            "description": "Array of recent contact records.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Contact"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Action: Create Contact"],
        "summary": "Create Contact (Inbound Action)",
        "description": "Creates a new contact in BoothMaven under the authenticated user's account. This powers the Zapier Action allowing third-party tools (Google Sheets, Typeform, Webforms, CRMs) to push leads directly into BoothMaven.",
        "security": [{ "bearerAuth": [] }, { "oauth2": ["contacts:read"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ContactCreateInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Contact created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Contact"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error - Missing required fields or invalid data format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/zapier/hooks/meetings/subscribe": {
      "post": {
        "tags": ["Trigger: New Meeting (REST Hooks)"],
        "summary": "Subscribe to New Meeting Webhook",
        "description": "Registers a new REST Hook subscription URL for the authenticated user. Whenever a meeting is scheduled in BoothMaven, BoothMaven sends an HTTP POST with the meeting payload to this URL.",
        "security": [{ "bearerAuth": [] }, { "oauth2": ["contacts:read"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SubscribeInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Webhook subscription created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscribeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error - Missing targetUrl.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": ["Trigger: New Meeting (REST Hooks)"],
        "summary": "Unsubscribe from New Meeting Webhook",
        "description": "Removes a meeting webhook subscription for the authenticated user.",
        "security": [{ "bearerAuth": [] }, { "oauth2": ["contacts:read"] }],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UnsubscribeInput"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Webhook subscription removed successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UnsubscribeResponse"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error - Neither `id` nor `targetUrl` provided.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          }
        }
      }
    },
    "/api/zapier/meetings": {
      "get": {
        "tags": ["Trigger: New Meeting (REST Hooks)"],
        "summary": "List Recent Meetings (Perform List / Sample Data)",
        "description": "Retrieves up to 20 of the most recently scheduled meetings for the authenticated user. Used by the Zap Editor to display sample meeting data for field mapping.",
        "security": [{ "bearerAuth": [] }, { "oauth2": ["contacts:read"] }],
        "responses": {
          "200": {
            "description": "Array of recent meeting records.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Meeting"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["Action: Create Meeting"],
        "summary": "Create Meeting (Inbound Action)",
        "description": "Schedules a new meeting in BoothMaven under the authenticated user's account. Used by Zapier to schedule meetings from external tools (Google Calendar, Calendly, Typeform, CRM).",
        "security": [{ "bearerAuth": [] }, { "oauth2": ["contacts:read"] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MeetingCreateInput"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Meeting created successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Meeting"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - Missing or invalid Bearer token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error - Missing required fields or invalid data format.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ValidationError"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.0 Authorization Code Grant",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.boothmaven.com/oauth/authorize",
            "tokenUrl": "https://api.boothmaven.com/oauth/token",
            "refreshUrl": "https://api.boothmaven.com/oauth/token",
            "scopes": {
              "contacts:read": "Read-only access to captured contacts and event details"
            }
          }
        }
      },
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Include your OAuth access token: `Authorization: Bearer <access_token>`"
      }
    },
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 42,
            "description": "Unique BoothMaven user ID"
          },
          "name": {
            "type": "string",
            "example": "Jane Doe",
            "description": "Full name of the user"
          },
          "username": {
            "type": "string",
            "example": "janedoe",
            "description": "BoothMaven username"
          },
          "email": {
            "type": "string",
            "format": "email",
            "example": "jane@example.com",
            "description": "Primary email address"
          }
        },
        "required": ["id", "name", "username", "email"]
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1001,
            "description": "Unique identifier of the contact in BoothMaven"
          },
          "first_name": {
            "type": "string",
            "example": "John",
            "description": "First name"
          },
          "last_name": {
            "type": "string",
            "nullable": true,
            "example": "Smith",
            "description": "Last name"
          },
          "email": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "example": "john.smith@example.com",
            "description": "Primary email address"
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "example": "+64 21 123 4567",
            "description": "Primary phone number"
          },
          "company": {
            "type": "string",
            "nullable": true,
            "example": "ABC Limited",
            "description": "Company or organization name"
          },
          "job_title": {
            "type": "string",
            "nullable": true,
            "example": "Marketing Manager",
            "description": "Job title or designation"
          },
          "event_id": {
            "type": "integer",
            "nullable": true,
            "example": 25,
            "description": "ID of the event where contact was captured"
          },
          "event_name": {
            "type": "string",
            "nullable": true,
            "example": "BoothMaven Expo 2026",
            "description": "Title of the associated event"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-14T10:30:00Z",
            "description": "Creation timestamp in UTC ISO 8601 format"
          }
        },
        "required": ["id", "first_name", "created_at"]
      },
      "ContactCreateInput": {
        "type": "object",
        "properties": {
          "first_name": {
            "type": "string",
            "maxLength": 255,
            "example": "Alice",
            "description": "Contact first name (required)"
          },
          "last_name": {
            "type": "string",
            "maxLength": 255,
            "nullable": true,
            "example": "Williams",
            "description": "Contact last name"
          },
          "email": {
            "type": "string",
            "format": "email",
            "maxLength": 255,
            "nullable": true,
            "example": "alice.williams@example.com",
            "description": "Contact email address"
          },
          "phone": {
            "type": "string",
            "maxLength": 50,
            "nullable": true,
            "example": "+1 555 234 5678",
            "description": "Contact phone number"
          },
          "company": {
            "type": "string",
            "maxLength": 255,
            "nullable": true,
            "example": "Tech Innovators Inc",
            "description": "Company name"
          },
          "job_title": {
            "type": "string",
            "maxLength": 255,
            "nullable": true,
            "example": "Senior Solutions Architect",
            "description": "Job title / designation"
          }
        },
        "required": ["first_name"]
      },
      "Meeting": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 5002,
            "description": "Unique identifier of the meeting"
          },
          "meeting_name": {
            "type": "string",
            "example": "Enterprise Demo Call",
            "description": "Title or subject of the meeting"
          },
          "meeting_status": {
            "type": "string",
            "example": "scheduled",
            "description": "Meeting status"
          },
          "meeting_format": {
            "type": "string",
            "nullable": true,
            "example": "virtual",
            "description": "Format (virtual, hybrid, inPerson)"
          },
          "priority": {
            "type": "string",
            "nullable": true,
            "example": "high",
            "description": "Priority level"
          },
          "meeting_date": {
            "type": "string",
            "format": "date",
            "example": "2026-11-01",
            "description": "Date of the meeting"
          },
          "meeting_time": {
            "type": "string",
            "example": "14:00:00",
            "description": "Time of the meeting"
          },
          "meeting_duration": {
            "type": "integer",
            "nullable": true,
            "example": 45,
            "description": "Duration in minutes"
          },
          "timezone": {
            "type": "string",
            "example": "UTC",
            "description": "Timezone identifier"
          },
          "meeting_location": {
            "type": "string",
            "nullable": true,
            "example": "https://meet.google.com/xyz",
            "description": "Meeting location or conference link"
          },
          "meeting_agenda": {
            "type": "string",
            "nullable": true,
            "example": "Review enterprise features and answer questions",
            "description": "Meeting agenda or notes"
          },
          "meeting_url": {
            "type": "string",
            "nullable": true,
            "example": "https://view.boothmaven.com/cards/meeting/xyz987",
            "description": "Public meeting card or booking link"
          },
          "booking_source": {
            "type": "string",
            "example": "zapier",
            "description": "Origin of the meeting booking"
          },
          "event_id": {
            "type": "integer",
            "nullable": true,
            "example": 25,
            "description": "Linked BoothMaven event ID"
          },
          "event_name": {
            "type": "string",
            "nullable": true,
            "example": "BoothMaven Expo 2026",
            "description": "Title of the associated event"
          },
          "primary_contact_id": {
            "type": "integer",
            "nullable": true,
            "example": 1001,
            "description": "Primary attendee contact ID"
          },
          "primary_contact_name": {
            "type": "string",
            "nullable": true,
            "example": "Lead Person",
            "description": "Primary attendee name"
          },
          "primary_contact_email": {
            "type": "string",
            "nullable": true,
            "example": "lead@example.com",
            "description": "Primary attendee email"
          },
          "contacts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MeetingContact"
            }
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-23T10:15:00Z",
            "description": "Creation timestamp in UTC ISO 8601 format"
          }
        },
        "required": [
          "id",
          "meeting_name",
          "meeting_status",
          "meeting_date",
          "meeting_time",
          "created_at"
        ]
      },
      "MeetingContact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 1001
          },
          "name": {
            "type": "string",
            "example": "Lead Person"
          },
          "email": {
            "type": "string",
            "nullable": true,
            "example": "lead@example.com"
          },
          "phone": {
            "type": "string",
            "nullable": true,
            "example": "+1234567890"
          },
          "company": {
            "type": "string",
            "nullable": true,
            "example": "Acme Inc"
          }
        }
      },
      "MeetingCreateInput": {
        "type": "object",
        "properties": {
          "meeting_name": {
            "type": "string",
            "maxLength": 191,
            "example": "Enterprise Demo Call",
            "description": "Meeting title or subject (required)"
          },
          "meeting_date": {
            "type": "string",
            "format": "date",
            "example": "2026-11-01",
            "description": "Date of meeting in YYYY-MM-DD format (required)"
          },
          "meeting_time": {
            "type": "string",
            "maxLength": 50,
            "example": "14:00:00",
            "description": "Time of meeting e.g. 14:00 or 14:00:00 (required)"
          },
          "meeting_duration": {
            "type": "integer",
            "nullable": true,
            "example": 45,
            "description": "Meeting duration in minutes (default 30)"
          },
          "meeting_format": {
            "type": "string",
            "enum": ["virtual", "hybrid", "inPerson"],
            "nullable": true,
            "example": "virtual",
            "description": "Format of meeting"
          },
          "priority": {
            "type": "string",
            "nullable": true,
            "example": "high",
            "description": "Priority level (high, medium, low)"
          },
          "meeting_location": {
            "type": "string",
            "maxLength": 191,
            "nullable": true,
            "example": "https://meet.google.com/xyz",
            "description": "Physical location or video call link"
          },
          "meeting_agenda": {
            "type": "string",
            "maxLength": 1000,
            "nullable": true,
            "example": "Review enterprise features and answer questions",
            "description": "Agenda or notes"
          },
          "timezone": {
            "type": "string",
            "maxLength": 100,
            "nullable": true,
            "example": "America/New_York",
            "description": "Timezone identifier (default UTC)"
          },
          "event_id": {
            "type": "integer",
            "nullable": true,
            "example": 25,
            "description": "Linked BoothMaven event ID"
          },
          "contact_id": {
            "oneOf": [
              { "type": "integer" },
              { "type": "array", "items": { "type": "integer" } }
            ],
            "nullable": true,
            "example": 1001,
            "description": "ID(s) of existing BoothMaven contact(s) to attach"
          },
          "contact_email": {
            "type": "string",
            "format": "email",
            "nullable": true,
            "example": "lead@example.com",
            "description": "Email of existing contact to link if contact_id is unknown"
          }
        },
        "required": ["meeting_name", "meeting_date", "meeting_time"]
      },
      "SubscribeInput": {
        "type": "object",
        "properties": {
          "targetUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
            "description": "Webhook callback URL provided by Zapier (camelCase)"
          },
          "target_url": {
            "type": "string",
            "format": "uri",
            "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
            "description": "Webhook callback URL provided by Zapier (snake_case alternative)"
          }
        }
      },
      "SubscribeResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 15,
            "description": "Subscription record ID"
          },
          "targetUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
          },
          "target_url": {
            "type": "string",
            "format": "uri",
            "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
          }
        },
        "required": ["id", "targetUrl", "target_url"]
      },
      "UnsubscribeInput": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "example": 15,
            "description": "Subscription record ID"
          },
          "targetUrl": {
            "type": "string",
            "format": "uri",
            "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef/",
            "description": "Target webhook URL to delete"
          },
          "target_url": {
            "type": "string",
            "format": "uri",
            "example": "https://hooks.zapier.com/hooks/catch/123456/abcdef/"
          }
        }
      },
      "UnsubscribeResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          }
        },
        "required": ["success"]
      },
      "TokenRequest": {
        "type": "object",
        "properties": {
          "grant_type": {
            "type": "string",
            "enum": ["authorization_code", "refresh_token"],
            "example": "authorization_code"
          },
          "client_id": {
            "type": "string",
            "example": "9a123456-7890-abcd-ef01-234567890abc"
          },
          "client_secret": {
            "type": "string",
            "example": "sec_abc123xyz789..."
          },
          "redirect_uri": {
            "type": "string",
            "format": "uri",
            "example": "https://zapier.com/dashboard/auth/oauth/return/App12345CLIAPI/"
          },
          "code": {
            "type": "string",
            "example": "def50200...",
            "description": "Required when grant_type is authorization_code"
          },
          "refresh_token": {
            "type": "string",
            "example": "def50200...",
            "description": "Required when grant_type is refresh_token"
          }
        },
        "required": ["grant_type", "client_id", "client_secret"]
      },
      "TokenResponse": {
        "type": "object",
        "properties": {
          "token_type": {
            "type": "string",
            "example": "Bearer"
          },
          "expires_in": {
            "type": "integer",
            "example": 31536000,
            "description": "Token validity duration in seconds (1 year)"
          },
          "access_token": {
            "type": "string",
            "example": "eyJ0eXAiOiJKV1QiLC..."
          },
          "refresh_token": {
            "type": "string",
            "example": "def50200..."
          }
        },
        "required": [
          "token_type",
          "expires_in",
          "access_token",
          "refresh_token"
        ]
      },
      "ValidationError": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "The targetUrl or target_url field is required and must be a valid URL."
          },
          "errors": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "example": {
              "targetUrl": ["A valid target URL is required."]
            }
          }
        },
        "required": ["message", "errors"]
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "example": "Unauthenticated."
          }
        },
        "required": ["message"]
      }
    }
  }
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.