GetResponse Forms API

openapi: 3.0.0
info:
  title: GetResponse APIv3 Forms
  version: 3.2026-07-28T07:58:55+00:00
  description: The Forms operations of the GetResponse APIv3, split by tag from the provider-published
    OpenAPI at https://apireference.getresponse.com/open-api.json
  contact:
    name: API Support - DevZone
    url: https://app.getresponse.com/feedback.html?devzone=yes
    email: getresponse-devzone@cs.getresponse.com
servers:
- url: https://api.getresponse.com/v3
  description: GetResponse
- url: https://api3.getresponse360.com/v3
  description: GetResponse MAX US
- url: https://api3.getresponse360.pl/v3
  description: GetResponse MAX PL
tags:
- name: Forms
  description: Forms API documentation
paths:
  /forms/{formId}:
    get:
      tags:
      - Forms
      summary: Get form by ID
      operationId: getForm
      parameters:
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          $ref: '#/components/responses/FormDetails'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context
                      section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method
                      details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota
                      window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
    parameters:
    - $ref: '#/components/parameters/formId'
  /forms/{formId}/variants:
    get:
      tags:
      - Forms
      summary: Get the list of form variants (A/B tests)
      operationId: getFormVariantList
      parameters:
      - $ref: '#/components/parameters/Fields'
      responses:
        '200':
          $ref: '#/components/responses/FormVariantList'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 404
                    code: 1013
                    codeDescription: The requested resource was not found
                    message: Resource not found
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1013
                    context:
                      contactId: pVyRW
                    uuid: 87b90a96-5ee5-4ca4-8180-ac00adcf62c7
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context
                      section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method
                      details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota
                      window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
    parameters:
    - $ref: '#/components/parameters/formId'
  /forms:
    get:
      tags:
      - Forms
      summary: Get the list of forms.
      description: You can filter the resource using criteria specified as `query[*]`. You can provide
        multiple criteria, to use AND logic. You can sort the resource using parameters specified as `sort[*]`.
        You can specify multiple fields to sort by.
      operationId: getFormList
      parameters:
      - name: query[name]
        in: query
        description: Search forms by name
        required: false
        schema:
          type: string
      - name: query[createdOn][from]
        in: query
        description: Search forms created from this date
        required: false
        schema:
          $ref: '#/components/schemas/DateOrDateTime'
      - name: query[createdOn][to]
        in: query
        description: Search forms created to this date
        required: false
        schema:
          $ref: '#/components/schemas/DateOrDateTime'
      - name: query[campaignId]
        in: query
        description: Search forms assigned to this list (campaign). You can pass multiple comma-separated
          values, eg. `Xd1P,sC7r`
        required: false
        schema:
          type: string
      - name: query[status]
        in: query
        description: Search by status. **Note:** `disabled` includes both `unpublished` and `draft` and
          `enabled` equals `published`
        required: false
        schema:
          type: string
          enum:
          - enabled
          - disabled
          - published
          - unpublished
          - draft
      - name: sort[createdOn]
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: sort[name]
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: sort[visitors]
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: sort[uniqueVisitors]
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: sort[subscribed]
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - name: sort[subscriptionRate]
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/SortOrderEnum'
      - $ref: '#/components/parameters/Fields'
      - $ref: '#/components/parameters/PerPage'
      - $ref: '#/components/parameters/Page'
      responses:
        '200':
          $ref: '#/components/responses/FormList'
        '400':
          description: Request validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 400
                    code: 1000
                    codeDescription: General error of validation process, more details should be in context
                      section
                    message: Validation error, see context section for more information
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1000
                    context:
                      validationType: searchFilter[query]
                      fieldName: name
                      originalName: lorem-ipsum
                      errorDescription: Not allowed search field
                    uuid: 77dabfd1-1fa7-4f9f-8d3f-487b4403e3aa
        '401':
          description: Authentication error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 401
                    code: 1014
                    codeDescription: Problem during authentication process, check headers!
                    message: Unable to authenticate request. Check credentials or authentication method
                      details
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1014
                    context:
                      authenticationType: auth_token
                    uuid: 62417847-4f12-4c25-9b3a-0b619a187efe
        '429':
          description: The throttling limit has been reached
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                example:
                  value:
                    httpStatus: 429
                    code: 1015
                    codeDescription: Too many request to API, quota reached, please wait till next quota
                      window
                    message: You have reached your requests limit for this time window, please wait...
                    moreInfo: https://apidocs.getresponse.com/en/v3/errors/1015
                    context:
                      currentLimit: 30000
                      timeToReset: 100 seconds
                    uuid: 510c6726-7f65-46b7-a798-ca403133924f
      security:
      - api-key: []
      - oauth2:
        - all
components:
  headers:
    CurrentPage:
      description: The current page number
      schema:
        type: integer
        format: int32
    RateLimitLimit:
      description: The total number of requests available per time frame
      schema:
        type: integer
        format: int32
    RateLimitRemaining:
      description: The number of requests left in the current time frame
      schema:
        type: integer
        format: int32
    RateLimitReset:
      description: Seconds left in the current time frame, e.g. "432 seconds"
      schema:
        type: string
    TotalCount:
      description: The total number of resources found for the specified conditions
      schema:
        type: integer
        format: int32
    TotalPages:
      description: The total number of pages
      schema:
        type: integer
        format: int32
  parameters:
    Fields:
      name: fields
      in: query
      description: List of fields that should be returned. Id is always returned. Fields should be separated
        by comma
      required: false
      schema:
        type: string
    Page:
      name: page
      in: query
      description: Page number
      required: false
      schema:
        type: integer
        format: int32
        default: 1
        minimum: 1
    PerPage:
      name: perPage
      in: query
      description: Requested number of results per page
      required: false
      schema:
        type: integer
        format: int32
        default: 100
        maximum: 1000
        minimum: 1
    formId:
      name: formId
      in: path
      description: The form ID
      required: true
      schema:
        type: string
      example: pL4e
  responses:
    FormDetails:
      description: The form details.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/FormDetails'
    FormList:
      description: The list of forms.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
        CurrentPage:
          $ref: '#/components/headers/CurrentPage'
        TotalPages:
          $ref: '#/components/headers/TotalPages'
        TotalCount:
          $ref: '#/components/headers/TotalCount'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/Form'
    FormVariantList:
      description: The list of form variants.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/RateLimitReset'
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/FormVariantDetails'
  schemas:
    CampaignReference:
      required:
      - campaignId
      properties:
        campaignId:
          description: Campaign ID
          type: string
          example: C
        href:
          description: Direct hyperlink to a resource
          type: string
          format: uri
          readOnly: true
          example: https://api.getresponse.com/v3/campaigns/C
        name:
          description: The campaign name
          type: string
          readOnly: true
          example: Promo campaign
          nullable: true
      type: object
    CustomFieldReference:
      properties:
        customFieldId:
          type: string
          readOnly: true
          example: pas
        name:
          description: "\nThe name of the custom field. It must meet the following requirements:\n * be\
            \ unique\n * use only lowercase letters, underscores and digits: [a-z0-9_]{1,128}\n * not\
            \ be equal to one of the merge words used in messages, i.e. `name`, `email`, `twitter`, `facebook`,\
            \ `buzz`, `myspace`, `linkedin`, `digg`, `googleplus`, `pinterest`, `responder`, `campaign`,\
            \ `change`."
          type: string
          maxLength: 128
          minLength: 1
          example: color
        values:
          description: The list of assigned default values, starting from zero depending on the custom
            field format. (Please see description).
          type: array
          items:
            type: string
            example: red
      type: object
    DateOrDateTime:
      oneOf:
      - type: string
        format: date
        example: '2018-04-15'
      - type: string
        format: date-time
        example: 2018-01-15T13:30:42+0000
    ErrorResponse:
      required:
      - httpStatus
      - code
      - codeDescription
      - message
      - moreInfo
      - context
      - uuid
      properties:
        httpStatus:
          description: HTTP response code
          type: integer
          format: int32
        code:
          description: API error code
          type: integer
          format: int32
        codeDescription:
          description: API error code description
          type: string
        message:
          description: Error message
          type: string
        moreInfo:
          description: URL to error description in the API Docs
          type: string
        context:
          type: object
        uuid:
          description: UUID of the error response
          type: string
      type: object
    Form:
      properties:
        formId:
          type: string
          readOnly: true
          example: pL4e
        webformId:
          description: Same as `formId`
          type: string
          readOnly: true
          example: pL4e
        name:
          type: string
          example: My first form
        href:
          description: Direct hyperlink to a resource
          type: string
          format: uri
          readOnly: true
          example: https://api.getresponse.com/v3/forms/pL4e
        hasVariants:
          description: Indicates if the form has variants (A/B tests)
          type: boolean
          readOnly: true
          example: true
        scriptUrl:
          description: The URL to a JavaScript file of the form. This is used to embed the form within
            a web page.
          type: string
          format: uri
          readOnly: true
          example: https://app.getresponse.com/view_webform_v2.js?u=nTfa&webforms_id=123
        status:
          type: string
          enum:
          - published
          - unpublished
          - draft
          example: published
        createdOn:
          type: string
          format: date-time
          example: 2018-07-02T11:22:33+0000
        statistics:
          $ref: '#/components/schemas/FormStatistics'
        campaign:
          $ref: '#/components/schemas/CampaignReference'
      type: object
    FormDetails:
      type: object
      allOf:
      - properties:
          settings:
            $ref: '#/components/schemas/FormSettings'
          variants:
            type: array
            items:
              $ref: '#/components/schemas/FormVariant'
        type: object
      - $ref: '#/components/schemas/Form'
    FormSettings:
      properties:
        optin:
          description: '`single` - Single opt-in means that the contact will be added without confirming
            their subscription first. `double` - Double opt-in means that the contact will receive a subscription
            confirmation email.'
          type: string
          enum:
          - single
          - double
          example: single
        phase:
          description: The contact who subscribed via this form will be added to the selected day in the
            autoresponder cycle. If null, the contact won't be added to the cycle.
          type: integer
          format: int32
          maximum: 9999
          minimum: 0
          example: 5
          nullable: true
        thankYouType:
          description: What should happen when a new contact subscribes via the form.
          type: string
          enum:
          - stay_on_page
          - default
          - custom_url
          example: stay_on_page
        thankYouUrl:
          description: The URL used to redirect the newly subscribed contacts when they complete this
            form. Used if `thankYouType` is `custom_url`.
          type: string
          format: uri
          example: https://example.com/thank-you
          nullable: true
        alreadySubscribedType:
          description: What to do when the address already exists in the campaign
          type: string
          enum:
          - stay_on_page
          - default
          - custom_url
          example: stay_on_page
        alreadySubscribedUrl:
          description: The URL used to redirect the already subscribed contacts when they complete this
            form. Used if `alreadySubscribedType` is `custom_url`.
          type: string
          format: uri
          example: https://example.com/thank-you
          nullable: true
        secondStageCaptcha:
          description: Is captcha enabled for the form
          allOf:
          - $ref: '#/components/schemas/StringBooleanEnum'
        forwardDataRequestType:
          description: How to forward form data to a thank-you page. [Learn more](https://www.getresponse.com/help/building-contact-lists/forms-and-pop-ups/can-i-forward-subscriber-data-to-a-custom-thank-you-page.html).
            `null` means that the data forwarding is turned off.
          type: string
          enum:
          - GET
          - POST
          nullable: true
        trackingCustomField:
          description: Subscribers added via this form will have this custom field set with a value passed
            in `trackingCustomFieldValue`
          type: object
          nullable: true
          allOf:
          - $ref: '#/components/schemas/CustomFieldReference'
        trackingCustomFieldValue:
          description: See the `trackingCustomField` description
          type: string
          example: '123'
          nullable: true
      type: object
    FormStatistics:
      properties:
        visitors:
          description: The total number of form visitors
          type: integer
          format: int64
          example: 4371
        uniqueVisitors:
          description: The number of unique form visitors
          type: integer
          format: int64
          example: 3865
        subscribed:
          description: The number of visitors that subscribed using this form
          type: integer
          format: int64
          example: 2594
        subscriptionRate:
          description: The ratio of `subscribed` to `visitors`
          type: number
          format: double
          example: 0.59
      type: object
    FormVariant:
      properties:
        variant:
          description: The index of variants
          type: string
          readOnly: true
          example: '0'
        variantName:
          type: string
          example: Variant A
        winner:
          description: Is this variant the winner in the A/B test
          allOf:
          - $ref: '#/components/schemas/StringBooleanEnum'
        status:
          type: string
          enum:
          - published
          - unpublished
          - disabled
        createdOn:
          type: string
          format: date-time
          example: 2018-07-11T13:37:25+0000
        statistics:
          $ref: '#/components/schemas/FormStatistics'
      type: object
    FormVariantDetails:
      properties:
        formId:
          type: string
          readOnly: true
          example: pL4e
        webformId:
          description: Same as `formId`
          type: string
          readOnly: true
          example: pL4e
        variant:
          description: The index of variants
          type: string
          readOnly: true
          example: '0'
        variantName:
          type: string
          example: Variant A
        winner:
          description: Is this variant the winner in the A/B test
          type: string
          enum:
          - 'yes'
          - 'no'
        status:
          type: string
          enum:
          - published
          - unpublished
          - disabled
        createdOn:
          type: string
          format: date-time
          example: 2018-07-09T15:45:12+0000
        numberOfVisitors:
          description: The total number of form visitors
          type: integer
          format: int64
          example: 152
        numberOfUniqueVisitors:
          description: The number of unique form visitors
          type: integer
          format: int64
          example: 136
        numberOfSubscribers:
          description: The number of visitors who subscribed through this form
          type: integer
          format: int64
          example: 94
        subscriptionRate:
          description: The ratio of `numberOfSubscribers` to `numberOfVisitors`
          type: number
          format: double
          example: 0.62
      type: object
    SortOrderEnum:
      type: string
      enum:
      - ASC
      - DESC
    StringBooleanEnum:
      type: string
      enum:
      - 'true'
      - 'false'
  securitySchemes:
    api-key:
      type: apiKey
      description: Header value must be prefixed with api-key
      name: X-Auth-Token
      in: header
    oauth2:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://app.getresponse.com/oauth2_authorize.html
          scopes:
            all: all data access
        authorizationCode:
          authorizationUrl: https://app.getresponse.com/oauth2_authorize.html
          tokenUrl: https://api.getresponse.com/v3/token
          scopes:
            all: all data access
        clientCredentials:
          tokenUrl: https://api.getresponse.com/v3/token
          scopes:
            all: all data access