forms.yml

imports:
  root: __package__.yml
service:
  auth: false
  base-path: ''
  endpoints:
    list:
      path: /sites/{site_id}/forms
      method: GET
      auth:
        - OAuth2:
            - forms:read
      docs: |
        List forms for a given site.

        Required scope | `forms:read`
      source:
        openapi: ../../../openapi/referenced-specs/v2.yml
      path-parameters:
        site_id:
          type: string
          docs: Unique identifier for a Site
      display-name: List Forms
      request:
        name: FormsListRequest
        query-parameters:
          limit:
            type: optional<double>
            docs: 'Maximum number of records to be returned (max limit: 100)'
          offset:
            type: optional<double>
            docs: >-
              Offset used for pagination if the results have more than limit
              records
      response:
        docs: Request was successful
        type: root.FormList
        status-code: 200
      errors:
        - root.BadRequestError
        - root.UnauthorizedError
        - root.ForbiddenError
        - root.NotFoundError
        - root.ConflictError
        - root.TooManyRequestsError
        - root.InternalServerError
      examples:
        - path-parameters:
            site_id: 580e63e98c9a982ac9b8b741
          query-parameters:
            limit: 1.1
            offset: 1.1
          response:
            body:
              forms:
                - displayName: Email Form
                  createdOn: '2016-10-24T19:41:29Z'
                  lastUpdated: '2016-10-24T19:43:17Z'
                  fields:
                    '0':
                      displayName: Email
                      placeholder: Enter your email
                      userVisible: true
                    '1':
                      displayName: Email
                      placeholder: Enter your email
                      userVisible: true
                  responseSettings:
                    redirectUrl: https://example.com
                    redirectMethod: GET
                    redirectAction: POST https://example.com
                    sendEmailConfirmation: true
                  id: 589a331aa51e760df7ccb89e
                  siteId: 580e63e98c9a982ac9b8b741
                  siteDomainId: 6419db964a9c436a4baf6248
                  pageId: 6419db964a9c43f6a3af6348
                  pageName: Home
                  formElementId: 4e038d2c-6a1e-4953-7be9-a59a2b453177
                  workspaceId: 580e63fc8c9a982ac9b8b744
                - displayName: Name Form
                  createdOn: '2016-10-24T19:41:29Z'
                  lastUpdated: '2016-10-24T19:43:17Z'
                  fields:
                    '0':
                      displayName: Email
                      placeholder: Enter your email
                      userVisible: true
                  responseSettings:
                    redirectUrl: https://example.com
                    redirectMethod: GET
                    redirectAction: POST https://example.com
                    sendEmailConfirmation: false
                  id: 580ff8d7ba3e45ba9fe588e9
                  siteId: 580e63e98c9a982ac9b8b741
                  siteDomainId: 6419db964a9c436a4baf6248
                  pageId: 6419db964a9c43f6a3af6348
                  pageName: Home
                  formElementId: 4e038d2c-6a1e-4953-7be9-a59a2b453177
                  workspaceId: 580e63fc8c9a982ac9b8b744
              pagination:
                limit: 25
                offset: 0
                total: 2
    get:
      path: /forms/{form_id}
      method: GET
      auth:
        - OAuth2:
            - forms:read
      docs: |
        Get information about a given form.

        Required scope | `forms:read`
      source:
        openapi: ../../../openapi/referenced-specs/v2.yml
      path-parameters:
        form_id:
          type: string
          docs: Unique identifier for a Form
      display-name: Get Form Schema
      response:
        docs: Request was successful
        type: root.Form
        status-code: 200
      errors:
        - root.BadRequestError
        - root.UnauthorizedError
        - root.ForbiddenError
        - root.NotFoundError
        - root.TooManyRequestsError
        - root.InternalServerError
      examples:
        - path-parameters:
            form_id: 580e63e98c9a982ac9b8b741
          response:
            body:
              displayName: Email Form
              createdOn: '2016-10-24T19:41:29Z'
              lastUpdated: '2016-10-24T19:43:17Z'
              fields:
                660d5bcc9c0772150459dfb1:
                  displayName: Name
                  type: Plain
                  placeholder: Enter your email
                  userVisible: true
                589a331aa51e760df7ccb89d:
                  displayName: Email
                  type: Email
                  placeholder: Enter your email
                  userVisible: true
              responseSettings:
                redirectUrl: https://example.com
                redirectMethod: GET
                redirectAction: POST https://example.com
                sendEmailConfirmation: true
              id: 589a331aa51e760df7ccb89e
              siteId: 580e63e98c9a982ac9b8b741
              siteDomainId: 6419db964a9c436a4baf6248
              pageId: 6419db964a9c43f6a3af6348
              pageName: Home
              formElementId: 4e038d2c-6a1e-4953-7be9-a59a2b453177
              workspaceId: 580e63fc8c9a982ac9b8b744
    list-submissions:
      path: /forms/{form_id}/submissions
      method: GET
      auth:
        - OAuth2:
            - forms:read
      docs: |
        List form submissions for a given form

        <Note title="Forms in components">
          When a form is used in a component definition, each instance of the form is considered a unique form.
          
          To get a combined list of submissions for a form that appears across multiple component instances, use the [List Form Submissions by Site](/data/reference/forms/form-submissions/list-submissions-by-site) endpoint.
        </Note>

        Required scope | `forms:read`
      source:
        openapi: ../../../openapi/referenced-specs/v2.yml
      path-parameters:
        form_id:
          type: string
          docs: Unique identifier for a Form
      display-name: List Form Submissions
      request:
        name: FormsListSubmissionsRequest
        query-parameters:
          offset:
            type: optional<double>
            docs: >-
              Offset used for pagination if the results have more than limit
              records
          limit:
            type: optional<double>
            docs: 'Maximum number of records to be returned (max limit: 100)'
      response:
        docs: Request was successful
        type: root.FormSubmissionList
        status-code: 200
      errors:
        - root.BadRequestError
        - root.UnauthorizedError
        - root.ForbiddenError
        - root.NotFoundError
        - root.TooManyRequestsError
        - root.InternalServerError
      examples:
        - path-parameters:
            form_id: 580e63e98c9a982ac9b8b741
          query-parameters:
            offset: 1.1
            limit: 1.1
          response:
            body:
              formSubmissions:
                - id: 6321ca84df3949bfc6752327
                  displayName: Sample Form
                  siteId: 62749158efef318abc8d5a0f
                  workspaceId: 62749158efef318abc8d5a0f
                  dateSubmitted: '2022-09-14T12:35:16Z'
                  formResponse:
                    First Name: Arthur
                    Last Name: Dent
                - id: 660d64fabf6e0a0d4edab981
                  displayName: Sample Form
                  siteId: 62749158efef318abc8d5a0f
                  workspaceId: 62749158efef318abc8d5a0f
                  dateSubmitted: '2022-09-14T12:35:16Z'
                  formResponse:
                    First Name: Ford
                    Last Name: Prefect
              pagination:
                limit: 25
                offset: 0
                total: 2
    get-submission:
      path: /form_submissions/{form_submission_id}
      method: GET
      auth:
        - OAuth2:
            - forms:read
      docs: |
        Get information about a given form submissio.

        Required scope | `forms:read`
      source:
        openapi: ../../../openapi/referenced-specs/v2.yml
      path-parameters:
        form_submission_id:
          type: string
          docs: Unique identifier for a Form Submission
      display-name: Get Form Submission
      response:
        docs: Request was successful
        type: root.FormSubmission
        status-code: 200
      errors:
        - root.BadRequestError
        - root.UnauthorizedError
        - root.ForbiddenError
        - root.NotFoundError
        - root.TooManyRequestsError
        - root.InternalServerError
      examples:
        - path-parameters:
            form_submission_id: 580e63e98c9a982ac9b8b741
          response:
            body:
              id: 6321ca84df3949bfc6752327
              displayName: Sample Form
              siteId: 62749158efef318abc8d5a0f
              workspaceId: 62749158efef318abc8d5a0f
              dateSubmitted: '2022-09-14T12:35:16Z'
              formResponse:
                First Name: Arthur
                Last Name: Dent
    delete-submission:
      path: /form_submissions/{form_submission_id}
      method: DELETE
      auth:
        - OAuth2:
            - forms:write
      docs: |
        Delete a form submission


        Required scope | `forms:write`
      source:
        openapi: ../../../openapi/referenced-specs/v2.yml
      path-parameters:
        form_submission_id:
          type: string
          docs: Unique identifier for a Form Submission
      display-name: Delete Form Submission
      errors:
        - root.BadRequestError
        - root.UnauthorizedError
        - root.ForbiddenError
        - root.NotFoundError
        - root.ConflictError
        - root.TooManyRequestsError
        - root.InternalServerError
      examples:
        - path-parameters:
            form_submission_id: 580e63e98c9a982ac9b8b741
    update-submission:
      path: /form_submissions/{form_submission_id}
      method: PATCH
      auth:
        - OAuth2:
            - forms:write
      docs: |
        Update hidden fields on a form submission

        Required scope | `forms:write`
      source:
        openapi: ../../../openapi/referenced-specs/v2.yml
      path-parameters:
        form_submission_id:
          type: string
          docs: Unique identifier for a Form Submission
      display-name: Modify Form Submission
      request:
        name: FormsUpdateSubmissionRequest
        body:
          properties:
            formSubmissionData:
              type: optional<map<string, unknown>>
              docs: >-
                An existing **hidden field** defined on the form schema, and the
                corresponding value to set
        content-type: application/json
      response:
        docs: Request was successful
        type: root.FormSubmission
        status-code: 200
      errors:
        - root.BadRequestError
        - root.UnauthorizedError
        - root.ForbiddenError
        - root.NotFoundError
        - root.ConflictError
        - root.TooManyRequestsError
        - root.InternalServerError
      examples:
        - path-parameters:
            form_submission_id: 580e63e98c9a982ac9b8b741
          request: {}
          response:
            body:
              id: 6321ca84df3949bfc6752327
              displayName: Sample Form
              siteId: 62749158efef318abc8d5a0f
              workspaceId: 62749158efef318abc8d5a0f
              dateSubmitted: '2022-09-14T12:35:16Z'
              formResponse:
                First Name: Arthur
                Last Name: Dent
  source:
    openapi: ../../../openapi/referenced-specs/v2.yml
  display-name: Forms
docs: Forms are forms that are created on your Webflow site.
webhooks:
  form_submission:
    audiences: []
    method: POST
    display-name: Form Submission
    headers: {}
    payload: root.FormSubmissionTrigger
    examples:
      - payload:
          triggerType: form_submission
          payload:
            name: Contact Us
            siteId: 65427cf400e02b306eaa049c
            data:
              First Name: Zaphod
              Last Name: Beeblebrox
              email: zaphod@heartofgold.ai
              Phone Number: 15550000000
            schema:
              - fieldName: First Name
                fieldType: FormTextInput
                fieldElementId: 285042f7-d554-dc7f-102c-aa10d6a2d2c4
              - fieldName: Last Name
                fieldType: FormTextInput
                fieldElementId: 285042f7-d554-dc7f-102c-aa10d6a2d2c5
              - fieldName: email
                fieldType: FormTextInput
                fieldElementId: 285042f7-d554-dc7f-102c-aa10d6a2d2c6
              - fieldName: Phone Number
                fieldType: FormTextInput
                fieldElementId: 285042f7-d554-dc7f-102c-aa10d6a2d2c7
            submittedAt: '2022-09-14T12:35:16.117Z'
            id: 6321ca84df3949bfc6752327
            formId: 65429eadebe8a9f3a30f62d0
            formElementId: 4e038d2c-6a1e-4953-7be9-a59a2b453177
    docs: Information about a form that was subitted