openapi: 3.0.3
info:
  title: Wufoo REST API
  description: |
    The Wufoo REST API v3 provides programmatic read and write access to a Wufoo
    account: Forms, Fields, Entries, Reports, Widgets, Comments, Users, and
    Webhooks. Every request is per-subdomain and authenticates with the account
    API key over HTTP Basic Auth. Endpoints support `.json` or `.xml` response
    formats by appending the extension to the URL.
  version: '3.0'
  contact:
    name: Wufoo Support
    url: https://help.surveymonkey.com/wufoo/
  license:
    name: Wufoo Terms of Use
    url: https://www.wufoo.com/terms-of-use/
servers:
  - url: https://{subdomain}.wufoo.com/api/v3
    description: Wufoo account subdomain
    variables:
      subdomain:
        default: account
        description: Your Wufoo account subdomain.
security:
  - basicAuth: []
tags:
  - name: Forms
    description: Read forms and their metadata.
  - name: Fields
    description: Read the field structure of a form or report.
  - name: Entries
    description: Read and create form submissions.
  - name: Reports
    description: Read reports built on top of forms.
  - name: Widgets
    description: Read widgets inside reports.
  - name: Comments
    description: Read comments attached to entries.
  - name: Users
    description: Read account user information.
  - name: Webhooks
    description: Subscribe to and unsubscribe from form submission webhooks.
  - name: Login
    description: Exchange credentials for an API key.
paths:
  /forms.{format}:
    get:
      tags: [Forms]
      summary: List All Forms
      description: Returns all forms accessible to the authenticated API key.
      operationId: listForms
      parameters:
        - $ref: '#/components/parameters/Format'
        - name: page
          in: query
          schema: { type: integer, default: 1, minimum: 1 }
        - name: limit
          in: query
          schema: { type: integer, default: 1000, maximum: 1000 }
        - name: includeTodayCount
          in: query
          schema: { type: boolean }
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: A list of forms.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Forms:
                    type: array
                    items: { $ref: '#/components/schemas/Form' }
  /forms/{identifier}.{format}:
    get:
      tags: [Forms]
      summary: Get Single Form
      description: Returns one form by its hash or title.
      operationId: getForm
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: includeTodayCount
          in: query
          schema: { type: boolean }
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: The requested form.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Forms:
                    type: array
                    items: { $ref: '#/components/schemas/Form' }
  /forms/{identifier}/fields.{format}:
    get:
      tags: [Fields]
      summary: List Form Fields
      description: Returns the field structure for the given form.
      operationId: listFormFields
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: system
          in: query
          description: Include system fields (IP, LastPage, CompleteSubmission, Status, PurchaseTotal, Currency, TransactionId, MerchantType).
          schema: { type: boolean }
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Field list for the form.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Fields:
                    type: array
                    items: { $ref: '#/components/schemas/Field' }
  /forms/{identifier}/entries.{format}:
    get:
      tags: [Entries]
      summary: List Form Entries
      description: Returns entries (submissions) for a form, with filtering and paging.
      operationId: listFormEntries
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: system
          in: query
          schema: { type: boolean }
        - name: pretty
          in: query
          schema: { type: boolean }
        - name: pageStart
          in: query
          schema: { type: integer, default: 0 }
        - name: pageSize
          in: query
          schema: { type: integer, default: 25, maximum: 100 }
        - name: sort
          in: query
          description: Field ID to sort by.
          schema: { type: string }
        - name: sortDirection
          in: query
          schema: { type: string, enum: [ASC, DESC] }
        - name: match
          in: query
          description: AND or OR when combining multiple Filter parameters.
          schema: { type: string, enum: [AND, OR] }
      responses:
        '200':
          description: Entries list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Entries:
                    type: array
                    items: { $ref: '#/components/schemas/Entry' }
    post:
      tags: [Entries]
      summary: Submit Form Entry
      description: Submits a new entry to the form. Body is form-encoded `Field{N}=value` pairs.
      operationId: submitFormEntry
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              additionalProperties: { type: string }
              example:
                Field1: Jane
                Field2: Doe
                Field3: jane@example.com
      responses:
        '200':
          description: Submission result.
          content:
            application/json:
              schema: { $ref: '#/components/schemas/SubmitResult' }
        '429':
          description: Slow Down — submission rate limit exceeded (50 per user per 5 minute sliding window).
  /forms/{identifier}/entries/count.{format}:
    get:
      tags: [Entries]
      summary: Count Form Entries
      description: Returns the number of entries for a form.
      operationId: countFormEntries
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Entry count for the form.
          content:
            application/json:
              schema:
                type: object
                properties:
                  EntryCount: { type: string }
  /forms/{identifier}/comments.{format}:
    get:
      tags: [Comments]
      summary: List Form Comments
      description: Returns comments left on entries for a form.
      operationId: listFormComments
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: entryId
          in: query
          schema: { type: integer }
        - name: pageStart
          in: query
          schema: { type: integer, default: 0 }
        - name: pageSize
          in: query
          schema: { type: integer, default: 25, maximum: 100 }
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Comment list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Comments:
                    type: array
                    items: { $ref: '#/components/schemas/Comment' }
  /forms/{identifier}/comments/count.{format}:
    get:
      tags: [Comments]
      summary: Count Form Comments
      description: Returns the count of comments for a form.
      operationId: countFormComments
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Comment count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Count: { type: integer }
  /reports.{format}:
    get:
      tags: [Reports]
      summary: List All Reports
      description: Returns all reports in the account.
      operationId: listReports
      parameters:
        - $ref: '#/components/parameters/Format'
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Report list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Reports:
                    type: array
                    items: { $ref: '#/components/schemas/Report' }
  /reports/{identifier}.{format}:
    get:
      tags: [Reports]
      summary: Get Single Report
      description: Returns one report by hash or title.
      operationId: getReport
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: The requested report.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Reports:
                    type: array
                    items: { $ref: '#/components/schemas/Report' }
  /reports/{identifier}/widgets.{format}:
    get:
      tags: [Widgets]
      summary: List Report Widgets
      description: Returns the widgets that compose a report.
      operationId: listReportWidgets
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Widget list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Widgets:
                    type: array
                    items: { $ref: '#/components/schemas/Widget' }
  /reports/{identifier}/entries.{format}:
    get:
      tags: [Reports, Entries]
      summary: List Report Entries
      description: Returns entries filtered by report criteria.
      operationId: listReportEntries
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: system
          in: query
          schema: { type: boolean }
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Entry list for the report.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Entries:
                    type: array
                    items: { $ref: '#/components/schemas/Entry' }
  /reports/{identifier}/entries/count.{format}:
    get:
      tags: [Reports, Entries]
      summary: Count Report Entries
      description: Returns the number of entries in the report.
      operationId: countReportEntries
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Report entry count.
          content:
            application/json:
              schema:
                type: object
                properties:
                  EntryCount: { type: string }
  /reports/{identifier}/fields.{format}:
    get:
      tags: [Reports, Fields]
      summary: List Report Fields
      description: Returns the field structure of the underlying report.
      operationId: listReportFields
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
        - name: system
          in: query
          schema: { type: boolean }
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: Report field list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Fields:
                    type: array
                    items: { $ref: '#/components/schemas/Field' }
  /users.{format}:
    get:
      tags: [Users]
      summary: List Account Users
      description: Returns all users in the account, including sub-users (each holds their own API key).
      operationId: listUsers
      parameters:
        - $ref: '#/components/parameters/Format'
        - name: pretty
          in: query
          schema: { type: boolean }
      responses:
        '200':
          description: User list.
          content:
            application/json:
              schema:
                type: object
                properties:
                  Users:
                    type: array
                    items: { $ref: '#/components/schemas/User' }
  /webhooks/{identifier}.{format}:
    put:
      tags: [Webhooks]
      summary: Add Form Webhook
      description: Subscribes a URL to receive webhook POSTs when the form is submitted. Up to 10 per form.
      operationId: putFormWebhook
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - $ref: '#/components/parameters/Format'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                  description: Subscriber endpoint to POST submissions to.
                handshakeKey:
                  type: string
                  description: Shared secret echoed back as `HandshakeKey` in payloads.
                metadata:
                  type: boolean
                  description: When true, include FormStructure and FieldStructure in payload.
      responses:
        '200':
          description: Webhook subscription created.
          content:
            application/json:
              schema:
                type: object
                properties:
                  WebHookPutResult:
                    type: object
                    properties:
                      Hash: { type: string }
  /webhooks/{identifier}/{hash}.{format}:
    delete:
      tags: [Webhooks]
      summary: Delete Form Webhook
      description: Unsubscribes a previously created webhook.
      operationId: deleteFormWebhook
      parameters:
        - $ref: '#/components/parameters/Identifier'
        - name: hash
          in: path
          required: true
          description: Webhook hash returned at creation time.
          schema: { type: string }
        - $ref: '#/components/parameters/Format'
      responses:
        '200':
          description: Webhook deleted.
          content:
            application/json:
              schema:
                type: object
                properties:
                  WebHookDeleteResult: { type: integer }
  /login.{format}:
    post:
      tags: [Login]
      summary: Exchange Credentials For API Key
      description: |
        Builders integrating Wufoo for third-party customers can exchange a user's
        email/password for that user's API key.
      operationId: login
      parameters:
        - $ref: '#/components/parameters/Format'
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [email, password, integrationKey]
              properties:
                email: { type: string, format: email }
                password: { type: string, format: password }
                integrationKey: { type: string }
                subdomain: { type: string }
      responses:
        '200':
          description: API key and subdomain for the user.
          content:
            application/json:
              schema:
                type: object
                properties:
                  ApiKey: { type: string }
                  Subdomain: { type: string }
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: |
        HTTP Basic Auth. Use your Wufoo API key as the username and any non-empty
        string as the password. Servers require TLS v1.0 or higher; SSLv3 and lower
        are blocked.
  parameters:
    Identifier:
      name: identifier
      in: path
      required: true
      description: Form or report hash (preferred) or its title.
      schema: { type: string }
    Format:
      name: format
      in: path
      required: true
      description: Response serialization format.
      schema:
        type: string
        enum: [json, xml]
        default: json
  schemas:
    Form:
      type: object
      properties:
        Name: { type: string }
        Description: { type: string }
        RedirectMessage: { type: string }
        Url: { type: string }
        Email: { type: string }
        IsPublic: { type: string }
        Language: { type: string }
        StartDate: { type: string }
        EndDate: { type: string }
        EntryLimit: { type: string }
        DateCreated: { type: string, format: date-time }
        DateUpdated: { type: string, format: date-time }
        Hash: { type: string }
        LinkFields: { type: string, format: uri }
        LinkEntries: { type: string, format: uri }
        LinkEntriesCount: { type: string, format: uri }
    Field:
      type: object
      properties:
        Title: { type: string }
        Instructions: { type: string }
        IsRequired: { type: string }
        ClassNames: { type: string }
        DefaultVal: { type: string }
        Page: { type: integer }
        Type: { type: string }
        ID: { type: string }
        SubFields:
          type: array
          items:
            type: object
            properties:
              DefaultVal: { type: string }
              Label: { type: string }
              ID: { type: string }
        Choices:
          type: array
          items:
            type: object
            properties:
              Label: { type: string }
              Score: { type: integer }
        HasOtherField: { type: boolean }
    Entry:
      type: object
      description: Submission keyed by `Field{ID}` plus audit fields.
      additionalProperties: true
      properties:
        EntryId: { type: string }
        DateCreated: { type: string, format: date-time }
        CreatedBy: { type: string }
        DateUpdated: { type: string, format: date-time }
        UpdatedBy: { type: string }
    SubmitResult:
      type: object
      properties:
        Success: { type: integer, enum: [0, 1] }
        EntryId: { type: integer }
        EntryLink: { type: string, format: uri }
        RedirectUrl: { type: string, format: uri }
        ErrorText: { type: string }
        FieldErrors:
          type: array
          items:
            type: object
            properties:
              ID: { type: string }
              ErrorText: { type: string }
    Report:
      type: object
      properties:
        Name: { type: string }
        IsPublic: { type: string }
        Url: { type: string }
        Description: { type: string }
        DateCreated: { type: string, format: date-time }
        DateUpdated: { type: string, format: date-time }
        Hash: { type: string }
        LinkFields: { type: string, format: uri }
        LinkEntries: { type: string, format: uri }
        LinkEntriesCount: { type: string, format: uri }
        LinkWidgets: { type: string, format: uri }
    Widget:
      type: object
      properties:
        Hash: { type: string }
        Name: { type: string }
        Size: { type: string }
        Type: { type: string }
        TypeDesc: { type: string }
        Report: { type: string }
    Comment:
      type: object
      properties:
        CommentId: { type: string }
        EntryId: { type: string }
        Text: { type: string }
        CommentedBy: { type: string }
        DateCreated: { type: string, format: date-time }
    User:
      type: object
      properties:
        User: { type: string }
        Email: { type: string }
        FirstName: { type: string }
        LastName: { type: string }
        Company: { type: string }
        TimeZone: { type: string }
        SubdomainPrefix: { type: string }
        Hash: { type: string }
        IsAccountOwner: { type: string }
        ApiKey: { type: string }
        LinkForms: { type: string, format: uri }
        LinkReports: { type: string, format: uri }