Marketo Forms API

openapi: 3.2.0
info:
  description: Marketo Engage Rest API
  version: '1.0'
  title: Marketo Engage Rest Forms API
  termsOfService: https://www.adobe.com/legal.html
  contact:
    name: Adobe Developer Relations
    url: https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/home
    email: ''
  license:
    name: API License Agreement
    url: https://experienceleague.adobe.com/en/docs/marketo-developer/marketo/api-license
servers:
- url: https://localhost:8080/
tags:
- name: Forms
  description: Form Controller
paths:
  /rest/asset/v1/form/byName.json:
    get:
      tags:
      - Forms
      summary: Get Form by Name
      description: 'Retrieves a form record by its name. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: getLpFormByNameUsingGET
      parameters:
      - name: name
        in: query
        description: Name of the form
        required: true
        schema:
          type: string
      - name: status
        in: query
        description: Status filter for draft or approved versions
        required: false
        schema:
          type: string
          enum:
          - approved
          - draft
      - name: folder
        in: query
        description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLpFormResponse'
  /rest/asset/v1/form/{id}.json:
    get:
      tags:
      - Forms
      summary: Get Form By Id
      description: 'Retrieves a form record by its id. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: getLpFormByIdUsingGET
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      - name: status
        in: query
        description: Status filter for draft or approved versions
        required: false
        schema:
          type: string
          enum:
          - approved
          - draft
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLpFormResponse'
    post:
      tags:
      - Forms
      summary: Update Form Metadata
      description: 'Updates the metadata of the target form. Required Permissions: Read-Write Assets'
      operationId: updateFormsUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLpFormResponse'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateFormMetaDataRequest'
        description: updateFormMetaDataRequest
        required: true
  /rest/asset/v1/form/{id}/approveDraft.json:
    post:
      tags:
      - Forms
      summary: Approve Form Draft
      description: 'Approves the current draft of the form. This will delete the current approved version of the form. Required Permissions: Approve Assets'
      operationId: approveFromUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLpFormResponse'
  /rest/asset/v1/form/{id}/clone.json:
    post:
      tags:
      - Forms
      summary: Clone Form
      description: 'Clones the target form. Required Permissions: Read-Write Assets'
      operationId: cloneLpFormsUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLpFormResponse'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CloneFormRequest'
        description: cloneFormRequest
  /rest/asset/v1/form/{id}/delete.json:
    post:
      tags:
      - Forms
      summary: Delete Form
      description: 'Deletes the target form. Forms which are in use by landing pages may not be deleted until they are removed from all landing pages. Required Permissions: Read-Write Assets'
      operationId: deleteFormByIdUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfIdResponse'
  /rest/asset/v1/form/{id}/discardDraft.json:
    post:
      tags:
      - Forms
      summary: Discard Form Draft
      description: 'Discards the current draft of the form. Required Permissions: Read-Write Assets'
      operationId: discardFormByIdUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfIdResponse'
  /rest/asset/v1/form/{id}/submitButton.json:
    post:
      tags:
      - Forms
      summary: Update Submit Button
      description: 'Updates the submit button configuration for the target form. Required Permissions: Read-Write Assets'
      operationId: updateFormSubmitButtonUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLpFormResponse'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/SubmitButtonRequest'
        description: submitButtonRequest
        required: true
  /rest/asset/v1/form/{id}/thankYouPage.json:
    get:
      tags:
      - Forms
      summary: Get Thank You Page by Form Id
      description: 'Returns the thank you page configuration for a given form. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: getThankYouPageByIdUsingGET
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      - name: status
        in: query
        description: Status filter for draft or approved versions
        required: false
        schema:
          type: string
          enum:
          - approved
          - draft
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfThankYouPageResponse'
    post:
      tags:
      - Forms
      summary: Update Thank You Page
      description: 'Updates the thank you page configuration for a given form. This update is destructive and the resulting draft will not have any memory of the previous configuration. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: updateThankYouPageByIdUsingPOST
      parameters:
      - name: id
        in: path
        description: id
        required: true
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfThankYouPageResponse'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/UpdateThankYouPageRequest'
        description: thankYouPageRequest
        required: true
  /rest/asset/v1/forms.json:
    get:
      tags:
      - Forms
      summary: Get Forms
      description: 'Retrieves a list of accessible form records from the target instance. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: browseForms2UsingGET
      parameters:
      - name: status
        in: query
        description: Status filter for draft or approved versions
        required: false
        schema:
          type: string
          enum:
          - approved
          - draft
      - name: folder
        in: query
        description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
        required: false
        schema:
          type: string
      - name: maxReturn
        in: query
        description: Maximum number of forms to return. Max 200, default 20
        required: false
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: Integer offset for paging
        required: false
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLpFormResponse'
    post:
      tags:
      - Forms
      summary: Create Form
      description: 'Creates a new form. Required Permissions: Read-Write Assets'
      operationId: createLpFormsUsingPOST
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfLpFormResponse'
      requestBody:
        content:
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateLpFormRequest'
        description: createFormRequest
        required: true
  /rest/asset/v1/form/{id}/usedBy.json:
    get:
      tags:
      - Forms
      summary: Get Form Used By
      description: 'Returns a list of asset records which depend on a given form. Required Permissions: Read-Only Assets, Read-Write Assets'
      operationId: getFormUsedByUsingGET
      parameters:
      - name: id
        in: path
        description: Id of the form
        required: true
        schema:
          type: integer
          format: int32
      - name: offset
        in: query
        description: Integer offset for paging
        required: false
        schema:
          type: integer
          format: int32
      - name: maxReturn
        in: query
        description: Maximum number of assets to return. Max 200, default 20
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResponseOfFormUsedByResponse'
components:
  schemas:
    LpFormResponse:
      type: object
      required:
      - buttonLabel
      - buttonLocation
      - folder
      - fontFamily
      - fontSize
      - knownVisitor
      - labelPosition
      - language
      - locale
      - progressiveProfiling
      - status
      - thankYouList
      - theme
      - waitingLabel
      properties:
        buttonLabel:
          type: string
          description: Label text of the button
        buttonLocation:
          type: integer
          format: int32
          description: Location in pixels of the button relative to the left of the form
        createdAt:
          type: string
          format: date-time
          description: Datetime the asset was created
        description:
          type: string
          description: Description of the asset
        folder:
          description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
          $ref: '#/components/schemas/Folder'
        fontFamily:
          type: string
          description: font-family property for the form
        fontSize:
          type: string
          description: font-size property of the form
        id:
          type: integer
          format: int64
          description: Id of the asset
        knownVisitor:
          description: Known visitor behavior for the form
          $ref: '#/components/schemas/FormKnownVisitorDTO'
        labelPosition:
          type: string
          description: Default positioning of labels.
        language:
          type: string
          description: Language of the form
        locale:
          type: string
          description: Locale of the form
        name:
          type: string
          description: Name of the asset
        progressiveProfiling:
          type: boolean
          description: Whether progressive profiling is enabled for the form
        status:
          type: string
          description: Status filter for draft or approved versions
          enum:
          - approved
          - draft
        thankYouList:
          type: array
          description: List of thank you page behaviors for the form
          items:
            $ref: '#/components/schemas/FormThankYouPageDTO'
        theme:
          type: string
          description: CSS theme for the form to use
        updatedAt:
          type: string
          format: date-time
          description: Datetime the asset was most recently updated
        url:
          type: string
          description: Url of the asset in the Marketo UI
        waitingLabel:
          type: string
          description: Waiting text of the button
    Error:
      type: object
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Error code of the error. See full list of error codes <a href="https://developers.marketo.com/rest-api/error-codes/">here</a>
        message:
          type: string
          description: Message describing the cause of the error
    Folder:
      type: object
      required:
      - id
      - type
      properties:
        id:
          type: integer
          format: int32
          description: Id of the folder
        type:
          type: string
          description: Type of folder
          enum:
          - Folder
          - Program
      description: JSON representation of a folder
    ThankYouPageRequest:
      type: object
      required:
      - followupType
      - followupValue
      - operator
      - subjectField
      - values
      properties:
        default:
          type: boolean
          description: When true, this is the default rule, and will be applied when a user does not qualify for any of the other rules
        followupType:
          type: string
          description: Type of followup. When set to url, will follow to the url set in followupValue. When set to lp, will follow to the Landing page with the id given in followupValue
        followupValue:
          type: string
          description: Where to follow to on submission. Given as a URL or and Integer depending on followupType
        operator:
          type: string
          description: Operator to evaluate aginst the subject field
        subjectField:
          type: string
          description: Field to apply to operator to
        values:
          type: array
          description: Comma-separated list of values to compare to with the operator
          items:
            type: string
    FormKnownVisitorDTO:
      type: object
      properties:
        template:
          type: string
        type:
          type: string
    ThankYouPageResponse:
      type: object
      properties:
        id:
          type: integer
          format: int32
        thankYouList:
          type: array
          items:
            $ref: '#/components/schemas/FormThankYouPageDTO'
    SubmitButtonRequest:
      type: object
      properties:
        buttonPosition:
          type: integer
          format: int32
          description: Location in pixels of the button relative to the left of the form
        buttonStyle:
          type: string
          description: Style of the button
        label:
          type: string
          description: Label text of the button
        waitingLabel:
          type: string
          description: Waiting text of the button
    ResponseOfFormUsedByResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        requestId:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/FormUsedByResponse'
        success:
          type: boolean
        warnings:
          type: array
          items:
            type: string
    CloneFormRequest:
      type: object
      required:
      - name
      - folder
      properties:
        name:
          type: string
          description: Name for the cloned form
        folder:
          description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
          $ref: '#/components/schemas/Folder'
        description:
          type: string
          description: Description of the cloned form
    UpdateFormMetaDataRequest:
      type: object
      properties:
        customCss:
          type: string
          description: Custom CSS to apply to the form
        description:
          type: string
          description: Description of the form
        fontFamily:
          type: string
          description: font-family property for the form
        fontSize:
          type: string
          description: font-size property of the form
        knownVisitor:
          description: Known visitor behavior for the form
          $ref: '#/components/schemas/FormKnownVisitorDTO'
        labelPosition:
          type: string
          description: Default positioning of labels.
        language:
          type: string
          description: Language of the form
        locale:
          type: string
          description: Locale of the form
        name:
          type: string
          description: Name of the form
        progressiveProfiling:
          type: boolean
          description: Whether progressive profiling is enabled for the form
        theme:
          type: string
          description: CSS theme for the form to use
    ResponseOfThankYouPageResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        requestId:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/ThankYouPageResponse'
        success:
          type: boolean
        warnings:
          type: array
          items:
            type: string
    CreateLpFormRequest:
      type: object
      required:
      - folder
      properties:
        description:
          type: string
          description: Description of the form
        folder:
          description: JSON representation of parent folder, with members 'id', and 'type' which may be 'Folder' or 'Program'
          $ref: '#/components/schemas/Folder'
        fontFamily:
          type: string
          description: font-family property for the form
        fontSize:
          type: string
          description: font-size property of the form
        knownVisitor:
          description: Known visitor behavior for the form
          $ref: '#/components/schemas/FormKnownVisitorDTO'
        labelPosition:
          type: string
          description: Default positioning of labels.
        language:
          type: string
          description: Language of the form
        locale:
          type: string
          description: Locale of the form
        name:
          type: string
          description: Name of the form
        progressiveProfiling:
          type: boolean
          description: Whether progressive profiling is enabled for the form
        theme:
          type: string
          description: CSS theme for the form to use
    FormUsedByResponse:
      type: object
      required:
      - id
      - name
      - type
      - status
      - updatedAt
      properties:
        id:
          type: integer
          format: int64
          description: Id of the asset
        name:
          type: string
          description: Name of the asset
        type:
          type: string
          description: Type of asset
        status:
          type: string
          description: Status filter for draft or approved versions
          enum:
          - approved
          - draft
        updatedAt:
          type: string
          format: date-time
          description: Datetime the asset was most recently updated
    FormThankYouPageDTO:
      type: object
      properties:
        default:
          type: boolean
        followupType:
          type: string
        followupValue:
          type: object
        operator:
          type: string
        subjectField:
          type: string
        values:
          type: array
          items:
            type: string
    ResponseOfLpFormResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        requestId:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/LpFormResponse'
        success:
          type: boolean
        warnings:
          type: array
          items:
            type: string
    IdResponse:
      type: object
      required:
      - id
      properties:
        id:
          type: integer
          format: int32
          description: Id of the asset
    UpdateThankYouPageRequest:
      type: object
      properties:
        thankyou:
          type: array
          description: JSON array of followup rules
          items:
            $ref: '#/components/schemas/ThankYouPageRequest'
    ResponseOfIdResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
        requestId:
          type: string
        result:
          type: array
          items:
            $ref: '#/components/schemas/IdResponse'
        success:
          type: boolean
        warnings:
          type: array
          items:
            type: string