Convert Zapier API

Public HTTP API used by the Convert Zapier integration to register webhooks and fetch sample data. You can also call it directly from any HTTP client.

Base URL: https://www.convertsite.com
Prefix: all endpoints are under /api/zapier
Content type: application/json for all request and response bodies

Authentication

All endpoints require a Bearer token:

Authorization: Bearer <api_key>

API keys are generated by workspace admins in Workspace Settings → Integrations → API keys. Each key is scoped to one workspace and inherits that workspace's access to apps ("sites").

Keys are stored hashed; the raw key is shown only once at creation.
A key's last_used_at is updated (at most hourly) on every authenticated request.
Revoking a key in the UI invalidates it immediately.

Authentication errors

Status	Body	Cause
`401 Unauthorized`	`{"error": "unauthorized"}`	Missing `Authorization` header, non-`Bearer` scheme, or key is unknown/revoked
`500 Internal Server Error`	(empty)	Infrastructure failure while validating the key — safe to retry

Rate limiting

Each workspace is limited to 16 requests per second across /api/zapier/*. Over the limit returns:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{"error": "rate limit exceeded"}

Clients should back off and retry.

Endpoints

1. Test authentication / fetch sample payloads

GET /api/zapier/triggers/test
GET /api/zapier/triggers/test?trigger_type=<name>

Used by Zapier to (a) verify credentials during connection setup and (b) fetch sample submission data to populate its field picker. Returns two sample payloads shaped like real submissions. When trigger_type is provided, sample fields are drawn from the field names configured on matching Zapier Trigger actions in the workspace.

Query parameters

Name	Type	Required	Description
`trigger_type`	string	no	Filters sample field names to those used on actions with this trigger type label

Response 200 OK

[
  {
    "id": "00000000-0000-0000-0000-000000000001",
    "trigger_type": "contact_form_submission",
    "triggered_at": "2024-01-01T12:00:00Z",
    "email": "sample email",
    "name": "sample name"
  },
  {
    "id": "00000000-0000-0000-0000-000000000002",
    "trigger_type": "contact_form_submission",
    "triggered_at": "2024-01-01T11:00:00Z",
    "email": "sample email",
    "name": "sample name"
  }
]

If no trigger_type is supplied, trigger_type defaults to "example_trigger" and no extra fields are included.

2. List available trigger types for an app

GET /api/zapier/triggers?site_id=<uuid>

Returns the distinct trigger_type labels configured on Zapier Trigger actions inside the given app. Primarily used by the Zapier UI to power a dropdown; third-party clients may use it for discovery.

Query parameters

Name	Type	Required	Description
`site_id`	UUID	yes	The Convert app ("site") ID. Must belong to the authenticated workspace.

Response 200 OK

[
  { "trigger_type": "contact_form_submission" },
  { "trigger_type": "demo_request" }
]

POST /api/zapier/hooks/subscribe

Registers a target URL to receive submissions for a given site_id + trigger_type. Called by Zapier when a user turns a Zap on.

Request body

{
  "target_url": "https://hooks.zapier.com/hooks/standard/1234/abcd/",
  "trigger_type": "contact_form_submission",
  "site_id": "1f3b7c9a-4f2e-4a11-9d6b-8d6d6b9e1234"
}

Field	Type	Required	Description
`target_url`	string	yes	Absolute HTTPS URL to POST submission payloads to
`trigger_type`	string	yes	Must match a `trigger_type` label configured on a Zapier Trigger action in the app
`site_id`	UUID	yes	Convert app ID. Must belong to the authenticated workspace.

Response 201 Created

{ "id": "a3b8fe2c-7f0a-4b55-9c37-4e1fbbe23456" }

Keep this id — it's required to unsubscribe later.

Errors

Status	Body	Cause
`400 Bad Request`	`{"error": "<reason>"}`	`target_url` is malformed or not an allowed hook URL
`403 Forbidden`	`{"error": "site does not belong to this workspace"}`	`site_id` is not owned by this workspace
`401`, `429`, `500`	(see above)	Auth / rate / infrastructure

4. Unsubscribe a webhook

DELETE /api/zapier/hooks/unsubscribe/{id}

Removes a previously registered subscription. Called by Zapier when a Zap is turned off or deleted.

Path parameters

Name	Type	Description
`id`	UUID	The subscription ID returned by the subscribe call

Responses

Status	Body	Meaning
`200 OK`	(empty)	Subscription deleted
`404 Not Found`	(empty)	No subscription with that ID exists in this workspace (idempotent — safe to treat as success)
`401`, `500`	(see above)	Auth / infrastructure

Webhook delivery (outbound to subscribers)

When a published Convert app fires a Zapier Trigger action, Convert sends a POST request to every registered target_url for that site_id + trigger_type. Delivery is best-effort:

Timeout: 30 seconds per request.
Retries: none. A single attempt is made per subscription per event.
Ordering: no ordering guarantee across subscriptions or events; deliveries run concurrently as background tasks.
Durability: deliveries are not persisted. If the Convert server restarts mid-delivery, in-flight webhooks are lost. Subscribers should implement their own idempotency (via the id field) and treat missed events as possible.
Failure handling: failing subscriptions are not auto-disabled; failures are logged server-side but the subscription remains active.

Payloads are flat JSON objects with these reserved fields:

Field	Type	Description
`id`	UUID	Unique submission ID
`trigger_type`	string	Matches the `trigger_type` of the subscription
`triggered_at`	ISO-8601 timestamp (UTC)	When the action fired

All additional fields come from the formulas configured on the action in the editor. Values are primitives (string, number, boolean, null) — no nested objects or arrays.

Example payload

{
  "id": "6b2f1d8e-0a9c-4f3d-8b2a-72f9b3c14567",
  "trigger_type": "contact_form_submission",
  "triggered_at": "2026-04-22T14:03:11Z",
  "email": "[email protected]",
  "name": "Jane Smith",
  "phone": "(555) 123-4567",
  "plan_interest": "pro"
}

Subscribers should return a 2xx status within 30 seconds.

Error response shape

Except for responses documented as empty-bodied, errors return JSON:

{ "error": "human-readable description" }

Status code summary

Code	Meaning
`200 OK`	Success
`201 Created`	Subscription created
`400 Bad Request`	Invalid request body (e.g. malformed `target_url`)
`401 Unauthorized`	Missing / invalid API key
`403 Forbidden`	API key does not grant access to the requested `site_id`
`404 Not Found`	Subscription ID not found (on unsubscribe)
`429 Too Many Requests`	Workspace rate limit exceeded
`500 Internal Server Error`	Server-side failure — retry with backoff

Changelog

2026-04 — Initial public release. Endpoints: GET /triggers/test, GET /triggers, POST /hooks/subscribe, DELETE /hooks/unsubscribe/{id}.

OpenAPI specification

openapi: 3.1.0
info:
  title: Convert Zapier API
  version: "1.0.0"
  summary: REST API for Convert's Zapier integration.
  description: |
    Public HTTP API used by the Convert Zapier integration to register webhooks
    and fetch sample submission data. Can also be called directly from any HTTP
    client.

    All endpoints require Bearer authentication with an API key generated in
    **Workspace Settings → Integrations → API keys**. Each key is scoped to one
    workspace.
  contact:
    name: Convert Support
    url: https://www.convertsite.com
  license:
    name: Proprietary
servers:
  - url: https://www.convertsite.com
    description: Production

security:
  - bearerAuth: []

tags:
  - name: Triggers
    description: Endpoints used by Zapier to discover and test triggers.
  - name: Hooks
    description: REST Hook subscription management.

paths:
  /api/zapier/triggers/test:
    get:
      tags: [Triggers]
      summary: Test authentication and fetch sample payloads
      description: |
        Used by Zapier to (a) verify credentials during connection setup and
        (b) fetch sample submission data to populate its field picker. Returns
        two sample payloads shaped like real submissions. When `trigger_type`
        is supplied, sample fields are drawn from the field names configured
        on matching Zapier Trigger actions in the workspace.
      operationId: testTrigger
      parameters:
        - in: query
          name: trigger_type
          required: false
          schema:
            type: string
          description: Filters sample field names to those used on actions with this trigger type label.
      responses:
        "200":
          description: Sample payloads
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SubmissionPayload"
              examples:
                sample:
                  value:
                    - id: "00000000-0000-0000-0000-000000000001"
                      trigger_type: contact_form_submission
                      triggered_at: "2024-01-01T12:00:00Z"
                      email: sample email
                      name: sample name
                    - id: "00000000-0000-0000-0000-000000000002"
                      trigger_type: contact_form_submission
                      triggered_at: "2024-01-01T11:00:00Z"
                      email: sample email
                      name: sample name
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"

  /api/zapier/triggers:
    get:
      tags: [Triggers]
      summary: List trigger types configured in an app
      description: |
        Returns the distinct `trigger_type` labels configured on Zapier Trigger
        actions inside the given app. Primarily used by the Zapier UI to power
        a dropdown; third-party clients may use it for discovery.
      operationId: listTriggerTypes
      parameters:
        - in: query
          name: site_id
          required: true
          schema:
            type: string
            format: uuid
          description: The Convert app ("site") ID. Must belong to the authenticated workspace.
      responses:
        "200":
          description: Array of trigger types
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  required: [trigger_type]
                  properties:
                    trigger_type:
                      type: string
              examples:
                sample:
                  value:
                    - trigger_type: contact_form_submission
                    - trigger_type: demo_request
        "401":
          $ref: "#/components/responses/Unauthorized"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"

  /api/zapier/hooks/subscribe:
    post:
      tags: [Hooks]
      summary: Subscribe a REST Hook
      description: |
        Registers a `target_url` to receive submissions for a given
        `site_id` + `trigger_type`. Called by Zapier when a user turns a Zap on.
      operationId: subscribeHook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubscribeRequest"
            examples:
              sample:
                value:
                  target_url: https://hooks.zapier.com/hooks/standard/1234/abcd/
                  trigger_type: contact_form_submission
                  site_id: 1f3b7c9a-4f2e-4a11-9d6b-8d6d6b9e1234
      responses:
        "201":
          description: Subscription created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubscribeResponse"
              examples:
                sample:
                  value:
                    id: a3b8fe2c-7f0a-4b55-9c37-4e1fbbe23456
        "400":
          description: Invalid request body (e.g. malformed target_url)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          description: Site does not belong to this workspace
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              examples:
                sample:
                  value:
                    error: site does not belong to this workspace
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"

  /api/zapier/hooks/unsubscribe/{id}:
    delete:
      tags: [Hooks]
      summary: Unsubscribe a REST Hook
      description: |
        Removes a previously registered subscription. Called by Zapier when a
        Zap is turned off or deleted. Treat `404` as success — unsubscribe is
        idempotent.
      operationId: unsubscribeHook
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
          description: The subscription ID returned by `POST /api/zapier/hooks/subscribe`.
      responses:
        "200":
          description: Subscription deleted
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: No subscription with that ID exists in this workspace
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          $ref: "#/components/responses/ServerError"

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API key issued in **Workspace Settings → Integrations → API keys**.
        Sent as `Authorization: Bearer <api_key>`.

  schemas:
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
          description: Human-readable error description.

    SubscribeRequest:
      type: object
      required: [target_url, trigger_type, site_id]
      properties:
        target_url:
          type: string
          format: uri
          description: Absolute HTTPS URL to POST submission payloads to.
        trigger_type:
          type: string
          description: Must match a `trigger_type` label configured on a Zapier Trigger action in the app.
        site_id:
          type: string
          format: uuid
          description: Convert app ID. Must belong to the authenticated workspace.

    SubscribeResponse:
      type: object
      required: [id]
      properties:
        id:
          type: string
          format: uuid
          description: Subscription ID — pass to `DELETE /api/zapier/hooks/unsubscribe/{id}` to remove.

    SubmissionPayload:
      type: object
      description: |
        Flat JSON object delivered to subscribed `target_url`s and returned as
        sample data. Reserved fields (`id`, `trigger_type`, `triggered_at`) are
        always present; additional fields come from the formulas configured on
        the Zapier Trigger action. All custom values are primitives (string,
        number, boolean, null) — no nested objects or arrays.
      required: [id, trigger_type, triggered_at]
      properties:
        id:
          type: string
          format: uuid
          description: Unique submission ID.
        trigger_type:
          type: string
          description: Matches the `trigger_type` of the subscription.
        triggered_at:
          type: string
          format: date-time
          description: ISO-8601 UTC timestamp of when the action fired.
      additionalProperties:
        oneOf:
          - type: string
          - type: number
          - type: boolean
          - type: "null"

  responses:
    Unauthorized:
      description: Missing, malformed, or revoked API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            sample:
              value:
                error: unauthorized
    RateLimited:
      description: Workspace rate limit of 16 req/s exceeded.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
          examples:
            sample:
              value:
                error: rate limit exceeded
    ServerError:
      description: Server-side failure. Safe to retry with backoff.

Was this helpful?