Dotdigital Pages and forms API

openapi: 3.2.0
info:
  title: Pages and forms API
  version: 2.0.1
  description: 'Retrieve pages and forms created in the account. Use this API to list all forms, retrieve a single form by ID, fetch forms updated since a given date, inspect a form''s field structure, and retrieve responses — either all responses for a form or those updated since a specific date.

    '
servers:
- url: https://{region}-api.dotdigital.com
  variables:
    region:
      default: r1
      enum:
      - r1
      - r2
      - r3
      description: The Dotdigital region id your account belongs to
security:
- basicAuth: []
tags:
- name: Pages and forms
paths:
  /v2/surveys:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get forms
      deprecated: false
      description: Gets a list of all forms in the account
      operationId: get-forms
      tags:
      - Pages and forms
      parameters:
      - name: assignedToAddressBookOnly
        in: query
        description: Set to true to only get surveys assigned from an address book. Set to false to only retrieve surveys that aren't assigned to an address book.
        required: false
        schema:
          type: boolean
      - name: select
        in: query
        description: Enter a number between 1 and 500 (0 is not a valid number). You can select a maximum of 500 results in a single request.
        required: false
        schema:
          type: integer
          format: int32
      - name: skip
        in: query
        description: This is the number of records you want to skip.
        required: false
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  name:
                    type: string
                    examples:
                    - Event Registration Form
                  url:
                    type: string
                    examples:
                    - https://r1.dotdigital-pages.com/001ln562-3411pu49
                  dateSurveyCreated:
                    type: string
                    examples:
                    - '2020-01-01 09:40:18.527000+00:00'
                  dateSurveyModified:
                    type: string
                    examples:
                    - '2020-01-02 09:40:18.527000+00:00'
                  state:
                    type: string
                    examples:
                    - Active
                  firstActiveDate:
                    type: string
                    examples:
                    - '2020-01-01 09:40:18.527000+00:00'
                  lastInactiveDate: {}
                  scheduledStartDate: {}
                  scheduledEndDate: {}
                  confirmationMode:
                    type: string
                    examples:
                    - Text
                  submissionMode:
                    type: string
                    examples:
                    - Single
                  fieldCount:
                    type: integer
                    default: 0
                    examples:
                    - 10
                  notifyCreatorOnResponse:
                    type: boolean
                    default: true
                    examples:
                    - false
                  respondentNotificationType:
                    type: string
                    examples:
                    - None
                  respondentNotificationCampaignId: {}
                  isAssignedToAddressBook:
                    type: boolean
                    default: true
                    examples:
                    - false
                  assignedAddressBookTarget:
                    type: string
                    examples:
                    - AllContacts
                  assignedSpecificAddressBookId: {}
                  firstResponseDate:
                    type: string
                    examples:
                    - '2020-01-02 09:40:18.527000+00:00'
                  lastResponseDate:
                    type: string
                    examples:
                    - '2020-01-06 09:40:18.527000+00:00'
                  totalCompleteResponses:
                    type: integer
                    default: 0
                    examples:
                    - 18
                  totalCompleteResponsesInLastDay:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  totalCompleteResponsesInLastWeek:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  totalIncompleteResponses:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  totalViews:
                    type: integer
                    default: 0
                    examples:
                    - 19
                  totalBounces:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  timeToCompleteMax:
                    type: integer
                    default: 0
                    examples:
                    - 12430747
                  timeToCompleteMin:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  timeToCompleteTotal:
                    type: integer
                    default: 0
                    examples:
                    - 12432973
                  sourceDirectTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceEmailTotal:
                    type: integer
                    default: 0
                    examples:
                    - 20
                  sourceEmbeddedTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourcePopoverTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceFacebookTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceTwitterTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceGooglePlusTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceOtherTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
              examples:
                Result:
                  summary: Result
                  value:
                    id: 1
                    name: Event Registration Form
                    url: https://r1.dotdigital-pages.com/001ln562-3411pu49
                    dateSurveyCreated: '2020-01-01 09:40:18.527000+00:00'
                    dateSurveyModified: '2020-01-02 09:40:18.527000+00:00'
                    state: Active
                    firstActiveDate: '2020-01-01 09:40:18.527000+00:00'
                    lastInactiveDate: null
                    scheduledStartDate: null
                    scheduledEndDate: null
                    confirmationMode: Text
                    submissionMode: Single
                    fieldCount: 10
                    notifyCreatorOnResponse: false
                    respondentNotificationType: None
                    respondentNotificationCampaignId: null
                    isAssignedToAddressBook: false
                    assignedAddressBookTarget: AllContacts
                    assignedSpecificAddressBookId: null
                    firstResponseDate: '2020-01-02 09:40:18.527000+00:00'
                    lastResponseDate: '2020-01-06 09:40:18.527000+00:00'
                    totalCompleteResponses: 18
                    totalCompleteResponsesInLastDay: 1
                    totalCompleteResponsesInLastWeek: 1
                    totalIncompleteResponses: 0
                    totalViews: 19
                    totalBounces: 1
                    timeToCompleteMax: 12430747
                    timeToCompleteMin: 1
                    timeToCompleteTotal: 12432973
                    sourceDirectTotal: 0
                    sourceEmailTotal: 20
                    sourceEmbeddedTotal: 0
                    sourcePopoverTotal: 0
                    sourceFacebookTotal: 0
                    sourceTwitterTotal: 0
                    sourceGooglePlusTotal: 0
                    sourceOtherTotal: 0
  /v2/surveys/{id}:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get form by ID
      deprecated: false
      description: Gets a single form by its ID
      operationId: get-form-by-id
      tags:
      - Pages and forms
      parameters:
      - name: id
        in: path
        description: The ID of the form, which needs to be included within the URL
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  name:
                    type: string
                    examples:
                    - Event Registration Form
                  url:
                    type: string
                    examples:
                    - https://r1.dotdigital-pages.com/001ln562-3411pu49
                  dateSurveyCreated:
                    type: string
                    examples:
                    - '2020-01-01 09:40:18.527000+00:00'
                  dateSurveyModified:
                    type: string
                    examples:
                    - '2020-01-02 09:40:18.527000+00:00'
                  state:
                    type: string
                    examples:
                    - Active
                  firstActiveDate:
                    type: string
                    examples:
                    - '2020-01-01 09:40:18.527000+00:00'
                  lastInactiveDate: {}
                  scheduledStartDate: {}
                  scheduledEndDate: {}
                  confirmationMode:
                    type: string
                    examples:
                    - Text
                  submissionMode:
                    type: string
                    examples:
                    - Single
                  fieldCount:
                    type: integer
                    default: 0
                    examples:
                    - 10
                  notifyCreatorOnResponse:
                    type: boolean
                    default: true
                    examples:
                    - false
                  respondentNotificationType:
                    type: string
                    examples:
                    - None
                  respondentNotificationCampaignId: {}
                  isAssignedToAddressBook:
                    type: boolean
                    default: true
                    examples:
                    - false
                  assignedAddressBookTarget:
                    type: string
                    examples:
                    - AllContacts
                  assignedSpecificAddressBookId: {}
                  firstResponseDate:
                    type: string
                    examples:
                    - '2020-01-01 09:40:18.527000+00:00'
                  lastResponseDate:
                    type: string
                    examples:
                    - '2020-01-06 09:40:18.527000+00:00'
                  totalCompleteResponses:
                    type: integer
                    default: 0
                    examples:
                    - 18
                  totalCompleteResponsesInLastDay:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  totalCompleteResponsesInLastWeek:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  totalIncompleteResponses:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  totalViews:
                    type: integer
                    default: 0
                    examples:
                    - 19
                  totalBounces:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  timeToCompleteMax:
                    type: integer
                    default: 0
                    examples:
                    - 12430747
                  timeToCompleteMin:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  timeToCompleteTotal:
                    type: integer
                    default: 0
                    examples:
                    - 12432973
                  sourceDirectTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceEmailTotal:
                    type: integer
                    default: 0
                    examples:
                    - 20
                  sourceEmbeddedTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourcePopoverTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceFacebookTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceTwitterTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceGooglePlusTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceOtherTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
              examples:
                Result:
                  summary: Result
                  value:
                    id: 1
                    name: Event Registration Form
                    url: https://r1.dotdigital-pages.com/001ln562-3411pu49
                    dateSurveyCreated: '2020-01-01 09:40:18.527000+00:00'
                    dateSurveyModified: '2020-01-02 09:40:18.527000+00:00'
                    state: Active
                    firstActiveDate: '2020-01-01 09:40:18.527000+00:00'
                    lastInactiveDate: null
                    scheduledStartDate: null
                    scheduledEndDate: null
                    confirmationMode: Text
                    submissionMode: Single
                    fieldCount: 10
                    notifyCreatorOnResponse: false
                    respondentNotificationType: None
                    respondentNotificationCampaignId: null
                    isAssignedToAddressBook: false
                    assignedAddressBookTarget: AllContacts
                    assignedSpecificAddressBookId: null
                    firstResponseDate: '2020-01-01 09:40:18.527000+00:00'
                    lastResponseDate: '2020-01-06 09:40:18.527000+00:00'
                    totalCompleteResponses: 18
                    totalCompleteResponsesInLastDay: 1
                    totalCompleteResponsesInLastWeek: 1
                    totalIncompleteResponses: 0
                    totalViews: 19
                    totalBounces: 1
                    timeToCompleteMax: 12430747
                    timeToCompleteMin: 1
                    timeToCompleteTotal: 12432973
                    sourceDirectTotal: 0
                    sourceEmailTotal: 20
                    sourceEmbeddedTotal: 0
                    sourcePopoverTotal: 0
                    sourceFacebookTotal: 0
                    sourceTwitterTotal: 0
                    sourceGooglePlusTotal: 0
                    sourceOtherTotal: 0
  /v2/surveys/with-activity-since/{date}:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get forms with activity since date
      deprecated: false
      description: Gets a list of forms in the account that have changed since the specified date
      operationId: get-forms-with-activity-since-date
      tags:
      - Pages and forms
      parameters:
      - name: date
        in: path
        description: The date from which any forms with activity are returned in [ISO 8601 format](https://www.w3.org/TR/xmlschema-2/#dateTime)
        required: true
        example: ''
        schema:
          type: string
          format: date
      - name: assignedToAddressBookOnly
        in: query
        description: Set to true to only get surveys assigned from an address book. Set to false to only retrieve surveys that aren't assigned to an address book.
        required: false
        schema:
          type: boolean
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  name:
                    type: string
                    examples:
                    - Event Registration Form
                  url:
                    type: string
                    examples:
                    - https://r1.dotdigital-pages.com/001ln562-3411pu49
                  dateSurveyCreated:
                    type: string
                    examples:
                    - '2020-01-01 09:40:18.527000+00:00'
                  dateSurveyModified:
                    type: string
                    examples:
                    - '2020-01-02 09:40:18.527000+00:00'
                  state:
                    type: string
                    examples:
                    - Active
                  firstActiveDate:
                    type: string
                    examples:
                    - '2020-01-01 09:40:18.527000+00:00'
                  lastInactiveDate: {}
                  scheduledStartDate: {}
                  scheduledEndDate: {}
                  confirmationMode:
                    type: string
                    examples:
                    - Text
                  submissionMode:
                    type: string
                    examples:
                    - Single
                  fieldCount:
                    type: integer
                    default: 0
                    examples:
                    - 10
                  notifyCreatorOnResponse:
                    type: boolean
                    default: true
                    examples:
                    - false
                  respondentNotificationType:
                    type: string
                    examples:
                    - None
                  respondentNotificationCampaignId: {}
                  isAssignedToAddressBook:
                    type: boolean
                    default: true
                    examples:
                    - false
                  assignedAddressBookTarget:
                    type: string
                    examples:
                    - AllContacts
                  assignedSpecificAddressBookId: {}
                  firstResponseDate:
                    type: string
                    examples:
                    - '2020-01-01 12:40:18.527000+00:00'
                  lastResponseDate:
                    type: string
                    examples:
                    - '2020-01-10 09:40:18.527000+00:00'
                  totalCompleteResponses:
                    type: integer
                    default: 0
                    examples:
                    - 18
                  totalCompleteResponsesInLastDay:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  totalCompleteResponsesInLastWeek:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  totalIncompleteResponses:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  totalViews:
                    type: integer
                    default: 0
                    examples:
                    - 19
                  totalBounces:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  timeToCompleteMax:
                    type: integer
                    default: 0
                    examples:
                    - 12430747
                  timeToCompleteMin:
                    type: integer
                    default: 0
                    examples:
                    - 1
                  timeToCompleteTotal:
                    type: integer
                    default: 0
                    examples:
                    - 12432973
                  sourceDirectTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceEmailTotal:
                    type: integer
                    default: 0
                    examples:
                    - 20
                  sourceEmbeddedTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourcePopoverTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceFacebookTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceTwitterTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceGooglePlusTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
                  sourceOtherTotal:
                    type: integer
                    default: 0
                    examples:
                    - 0
              examples:
                Result:
                  summary: Result
                  value:
                    id: 1
                    name: Event Registration Form
                    url: https://r1.dotdigital-pages.com/001ln562-3411pu49
                    dateSurveyCreated: '2020-01-01 09:40:18.527000+00:00'
                    dateSurveyModified: '2020-01-02 09:40:18.527000+00:00'
                    state: Active
                    firstActiveDate: '2020-01-01 09:40:18.527000+00:00'
                    lastInactiveDate: null
                    scheduledStartDate: null
                    scheduledEndDate: null
                    confirmationMode: Text
                    submissionMode: Single
                    fieldCount: 10
                    notifyCreatorOnResponse: false
                    respondentNotificationType: None
                    respondentNotificationCampaignId: null
                    isAssignedToAddressBook: false
                    assignedAddressBookTarget: AllContacts
                    assignedSpecificAddressBookId: null
                    firstResponseDate: '2020-01-01 12:40:18.527000+00:00'
                    lastResponseDate: '2020-01-10 09:40:18.527000+00:00'
                    totalCompleteResponses: 18
                    totalCompleteResponsesInLastDay: 1
                    totalCompleteResponsesInLastWeek: 1
                    totalIncompleteResponses: 0
                    totalViews: 19
                    totalBounces: 1
                    timeToCompleteMax: 12430747
                    timeToCompleteMin: 1
                    timeToCompleteTotal: 12432973
                    sourceDirectTotal: 0
                    sourceEmailTotal: 20
                    sourceEmbeddedTotal: 0
                    sourcePopoverTotal: 0
                    sourceFacebookTotal: 0
                    sourceTwitterTotal: 0
                    sourceGooglePlusTotal: 0
                    sourceOtherTotal: 0
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                properties: {}
              examples:
                Result:
                  summary: Result
                  value: {}
  /v2/surveys/{id}/fields:
    parameters:
    - in: header
      name: x-ddg-integration-token
      required: false
      description: If you are a partner of Dotdigital and have a [verified integration](https://developer.dotdigital.com/docs/partner-integration-verification) then include your [integration tracking token](https://developer.dotdigital.co/docs/verified-integration-tracking) here.
      schema:
        type: string
        pattern: /^(?:\{{0,1}(?:[0-9a-fA-F]){8}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){4}-(?:[0-9a-fA-F]){12}\}{0,1})$/
        example: 5a96bc79-19a7-4544-973b-e2da0c9136f9
    get:
      summary: Get form fields
      deprecated: false
      description: Gets a list of a form's pages, each containing a list of the fields on that page
      operationId: get-form-fields
      tags:
      - Pages and forms
      parameters:
      - name: id
        in: path
        description: The ID of the form you want to get the fields from.
        required: true
        example: 0
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: integer
                      default: 0
                      examples:
                      - 1
                    name: {}
                    fields:
                      type: array
                      items:
                        type: object
                        properties:
                          id:
                            type: integer
                            default: 0
                            examples:
                            - 15
                          type:
                            type: string
                            examples:
                            - email
                          text:
                            type: string
                            examples:
                            - Email address
                          isRequired:
                            type: boolean
                            default: true
                            examples:
                            - true
                          defaultValue: {}
                          mode:
                            type: string
                            examples:
                            - singleline
                          choices:
                            type: array
                            items:
                              type: string
                          subFields:
                            type: array
                            items:
                              type: string
                          hasOtherOption:
                            type: boolean
                            default: true
                            examples:
                            - false
                          otherOptionChoiceId:
                            type: integer
                            default: 0
                            examples:
                            - 0
                          otherOptionSubFieldId:
                            type: integer
                            default: 0
                            examples:
                            - 0
                          otherOptionTextFieldId:
                            type: integer
                            default: 0
                            examples:
                            - 0
                          isAssignedToContactDataField:
                            type: boolean
                            default: true
                            examples:
                            - true
                          assignedContactDataFieldName:
                            type: string
                            examples:
                            - Email
                          assignedContactDataExistsAction:
                            type: string
                            examples:
                            - OverwriteData
              examples:
                Result:
                  summary: Result
                  value:
                  - id: 1
                    name: null
                    fields:
                    - id: 15
                      type: email
                      text: Email address
                      isRequired: true
                      defaultValue: null
                      mode: singleline
                      choices: []
                      subFields: []
                      hasOtherOption: false
                      otherOptionChoiceId: 0
                      otherOptionSubFieldId: 0
                      otherOptionTextFieldId: 0
                      isAssignedToContactDataField: true
                      assignedContactDataFieldName: Email
                      assignedContactDataExistsAction: OverwriteData
                    - id: 9
                      type: radiolist
                      text: 'Please could you select your age range from the list below:'
                      isRequired: false
                      defaultValue: null
                      mode:

# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dotdigital/refs/heads/main/openapi/dotdigital-pages-and-forms-api-openapi.yml