openapi: 3.1.0 info: title: Pages and forms 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. ' x-readme: headers: [] explorer-enabled: true proxy-enabled: true x-readme-fauxas: true x-samples-languages: - curl - csharp - java - javascript - node - python - php - ruby externalDocs: description: Learn more about Dotdigital APIs url: https://developer.dotdigital.com 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: [] components: securitySchemes: basicAuth: type: http scheme: basic 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: null choices: - id: 2 text: Under 18 - id: 3 text: 18-24 - id: 4 text: 25-34 - id: 5 text: 35-44 - id: 6 text: 45-54 - id: 7 text: 55-64 - id: 8 text: 65 or Above subFields: [] hasOtherOption: false otherOptionChoiceId: 0 otherOptionSubFieldId: 0 otherOptionTextFieldId: 0 isAssignedToContactDataField: false assignedContactDataFieldName: null assignedContactDataExistsAction: OverwriteData /v2/surveys/{id}/responses: 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 responses deprecated: false description: Gets a list of all responses for a specified form operationId: get-form-responses tags: - Pages and forms parameters: - name: id in: path description: The ID of the form to get responses 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 email: type: string examples: - john.smith@example.com started: type: boolean default: true examples: - true dateStarted: type: string examples: - '2020-01-01 09:40:18.527000+00:00' complete: type: boolean default: true examples: - true dateCompleted: type: string examples: - '2020-01-01 10:40:18.527000+00:00' givenAnswers: type: array items: type: object properties: fieldId: type: integer default: 0 examples: - 15 subFieldId: {} value: type: string examples: - john.smith@example.com examples: Result: summary: Result value: - id: 1 email: john.smith@example.com started: true dateStarted: '2020-01-01 09:40:18.527000+00:00' complete: true dateCompleted: '2020-01-01 10:40:18.527000+00:00' givenAnswers: - fieldId: 15 subFieldId: null value: john.smith@example.com - fieldId: 9 subFieldId: null value: 6 /v2/surveys/{id}/responses/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 form responses with activity since date deprecated: false description: Gets a list of responses that have changed since the specified date operationId: get-form-responses-with-activity-since-date tags: - Pages and forms parameters: - name: id in: path description: The ID of the form to get responses from. required: true example: 0 schema: type: integer format: int32 - name: date in: path description: 'The date from which responses with activity are returned. Format: ISO 8601.' required: true example: '' schema: type: string format: date responses: '200': description: '200' content: application/json: schema: type: object properties: id: type: integer default: 0 examples: - 1 email: type: string examples: - john.smith@example.com started: type: boolean default: true examples: - true dateStarted: type: string examples: - '2020-01-01 09:40:18.527000+00:00' complete: type: boolean default: true examples: - true dateCompleted: type: string examples: - '2020-01-01 09:40:18.527000+00:00' givenAnswers: type: array items: type: object properties: fieldId: type: integer default: 0 examples: - 15 subFieldId: {} value: type: string examples: - john.smith@example.com examples: Result: summary: Result value: id: 1 email: john.smith@example.com started: true dateStarted: '2020-01-01 09:40:18.527000+00:00' complete: true dateCompleted: '2020-01-01 09:40:18.527000+00:00' givenAnswers: - fieldId: 15 subFieldId: null value: john.smith@example.com - fieldId: 9 subFieldId: null value: 6