openapi: 3.1.0
info:
  title: Collectform Zapier API
  version: "1.0.0"
  description: >
    Endpoints the Collectform Zapier integration calls. Authentication is a
    per-form API key sent in the X-API-Key header, generated in the Collectform
    form builder under Integrations, Zapier. Each key is bound to a single form,
    so it both authenticates the request and selects which form's data is
    returned. See the full guide at
    https://collectform.com/blog/connect-collectform-to-zapier
  contact:
    name: Collectform
    url: https://collectform.com
servers:
  - url: https://api.collectform.com
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/zapier/me:
    get:
      operationId: getMe
      summary: Test authentication and return the connected form
      description: >
        Called by Zapier when a user connects their account. Validates the API
        key and returns the form the key is bound to. formName is used as the
        Zapier connection label.
      responses:
        "200":
          description: The key is valid.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Connection"
        "401":
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /api/zapier/submissions:
    get:
      operationId: listSubmissions
      summary: Poll for new completed submissions (New Submission trigger)
      description: >
        Returns up to the 50 newest completed submissions for the form bound to
        the API key, ordered newest first. Zapier deduplicates across polls
        using each item's id, so no cursor or since parameter is required.
        Submissions that were started but never completed are not returned.
      responses:
        "200":
          description: A list of submissions, newest first.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Submission"
        "401":
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >
        Per-form key (prefixed cf_live_) generated in the Collectform Zapier
        integration dialog. Treat it like a password.
  schemas:
    Connection:
      type: object
      required: [formId, formName, label]
      properties:
        formId:
          type: string
          example: "a1b2c3d4e5f6g7h"
        formName:
          type: string
          example: "Homepage demo request"
        label:
          type: string
          description: The connection name set in Collectform, may be empty.
          example: "Sheets, homepage demo form"
    Submission:
      type: object
      required: [id, submittedAt, formId, formName, fields, variables, hiddenFields, userData]
      properties:
        id:
          type: string
          description: Unique, stable submission id. Zapier's deduplication key.
          example: "r1a2b3c4d5e6f7g"
        submittedAt:
          type: string
          format: date-time
          example: "2026-07-18T14:32:05.123Z"
        formId:
          type: string
          example: "a1b2c3d4e5f6g7h"
        formName:
          type: string
          example: "Homepage demo request"
        fields:
          type: object
          description: >
            Answers keyed by question text. Values vary by field type: string,
            number, array, or object. A blank or duplicate question title falls
            back to the block id or a numbered suffix so no answer is
            overwritten.
          additionalProperties: true
          example:
            "What's your email?": "jane@example.com"
            "Full name": "Jane Doe"
            "Which plans interest you?": ["Pro", "Scale"]
        variables:
          type: object
          description: >
            Computed logic variables keyed by variable name (for example a lead
            score from calculate actions). Empty object when the form has none.
          additionalProperties: true
          example:
            score: 42
        hiddenFields:
          type: object
          description: >
            URL query params captured on load, limited to the form's allowed
            hidden-field list (for example utm_source). Empty object when none
            were passed.
          additionalProperties: true
          example:
            utm_source: "google"
        userData:
          type: object
          description: >
            Ad click identifiers captured for conversion matching (fbp, fbc,
            ttp). Present only when the form has a Meta or TikTok integration,
            and may be empty.
          additionalProperties: true
          example:
            fbp: "fb.1.1718900000000.1234567890"
            fbc: "fb.1.1718900000000.AbCdEf"
    Error:
      type: object
      required: [error]
      properties:
        error:
          type: string
          example: "Invalid or missing API key."