Forms

Summary of forms endpoints

• GET /admin/api/forms — list all available forms for the current site.
• GET /admin/api/forms/1 — get data for a single form.
• PUT /admin/api/forms/1 — update attributes of a form.
• DELETE /admin/api/forms/1 — delete a form.

Related endpoints:

• GET /admin/api/forms/1/tickets

List all available forms for the current site

GET /admin/api/forms

List all available forms for the current site. Note: If the form is deleted page then there is no content and parent attributes in object response.

Example response:

Status: 200 OK

[
  {
    "id": 1,
    "title": "Home Page",
    "created_at": "2014-01-13T09:19:04.000Z",
    "updated_at": "2014-01-13T09:19:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/forms/1",
    "tickets": "http://helloworld.voog.co/admin/api/forms/1/tickets"
  }, {
    "id": 2,
    "title": "Contact",
    "created_at": "2014-01-14T10:22:04.000Z",
    "updated_at": "2014-01-14T10:22:04.000Z",
    "url": "http://helloworld.voog.co/admin/api/forms/2",
    "tickets": "http://helloworld.voog.co/admin/api/forms/2/tickets",
    "content": {
      "id": 3,
      "name": "body",
      "position": 1,
      "created_at": "2014-01-14T10:22:04.000Z",
      "updated_at": "2014-01-14T10:22:04.000Z",
      "url": "http://helloworld.voog.co/admin/api/pages/1/contents/3"
    },
    "parent": {
      "id": 1,
      "title": "Home Page",
      "type": "page",
      "created_at": "2014-01-13T09:19:04.000Z",
      "updated_at": "2014-01-13T09:19:04.000Z",
      "url": "http://helloworld.voog.co/admin/api/pages/1",
      "public_url": "http://helloworld.voog.co/en"
    }
  }
]

Parameters

• per_page — elements per response (default: 50; maximum: 250).
• page — requested page (default: 1).
• parent_id and parent_type — parent id and type. Returns forms for parent. If present then both parameters are required. Allowed values for parent_type are:
  • page — parent is page.
  • language — parent is language.
  • article — parent is article.
• include_details — if present, the listing includes extra details, as the single form endpoint.

Filter attributes

Read more about filters.

• Object form attributes: id, title, description, fields, submit_emails, submit_label, submit_email_subject, created_at, updated_at.
• Object content attributes: id, parent_id, language_id, content_id, content_type, page_id, page_type, name, position, created_at, updated_at.

Get data for a single form

GET /admin/api/forms/1

Example request:

GET http://helloworld.voog.co/admin/api/forms/2

Example response:

Status: 200 OK

{
  "id": 2,
  "title": "Contact",
  "created_at": "2014-01-14T11:43:42.000Z",
  "updated_at": "2014-01-14T11:44:07.000Z",
  "url": "http://helloworld.voog.co/admin/api/forms/2",
  "tickets": "http://helloworld.voog.co/admin/api/forms/2/tickets",
  "content": {
    "id": 2,
    "name": "body",
    "position": 2,
    "created_at": "2014-01-14T11:43:42.000Z",
    "updated_at": "2014-01-14T11:43:42.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/3/contents/2"
  },
  "parent": {
    "id": 3,
    "title": "Contact",
    "type": "page",
    "created_at": "2014-01-14T11:43:37.000Z",
    "updated_at": "2014-01-14T11:43:37.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/3",
    "public_url": "http://helloworld.voog.co/contact"
  },
  "description": null,
  "fields": [{
    "id": "field_1389863908580",
    "type": "textfield",
    "title": "Simple text field",
    "required": false,
    "field_size": "small",
    "classname": "my-field",
    "placeholder": "This is placeholder"
  }, {
    "id": "field_1389863978349",
    "type": "textfield",
    "title": "Email field",
    "required": false,
    "field_size": "medium",
    "format": "email",
    "classname": "my-email-field",
    "placeholder": "Enter your email"
  }, {
    "id": "field_1389864022045",
    "type": "textfield",
    "title": "Web addres",
    "required": false,
    "field_size": "large",
    "format": "webaddress",
    "classname": "my-web-field",
    "placeholder": "http://"
  }, {
    "id": "field_1389864067243",
    "type": "textarea",
    "title": "Multiline text",
    "required": false,
    "field_size": "large",
    "classname": "my-multiline-field",
    "placeholder": "Enter your story"
  }, {
    "id": "field_1389864095155",
    "type": "select",
    "title": "Select list",
    "required": false,
    "options": [
      "Option 1",
      "Option 2",
      "Option 3"
    ],
    "classname": "my-select"
  }, {
    "id": "field_1389864130096",
    "type": "checkbox",
    "title": "Checkboxes",
    "required": false,
    "options": [
      "Checkbox 1",
      "Checkbox 2",
      "Checkbox 3"
    ],
    "classname": "my-checkboxes"
  }, {
    "id": "field_1389864153264",
    "type": "radio",
    "title": "Single choice",
    "required": false,
    "options": [
      "Choice 1",
      "Choice 2",
      "Choice 3"
    ],
    "classname": "my-radiobuttons"
  }, {
    "id": "field_1389864181776",
    "type": "file",
    "title": "File upload",
    "required": false,
    "classname": "my-file-upload-field"
  }],
  "submit_emails": "test@example.com,test@xn--t-zga.nu",
  "submit_emails_with_idn": "test@example.com,test@tõ.nu",
  "submit_label": "Send form",
  "submit_email_subject": "Email from page",
  "submit_action": null,
  "submit_success_message": null,
  "submit_success_address": null,
  "submit_failure_message": null,
  "classname": null,
  "recaptcha": null
}

Update attributes of a form

PUT /admin/api/forms/1

Example request:

PUT http://helloworld.voog.co/admin/api/forms/2

Example data:

{
  "title": "Form new name",
  "submit_label": "Click me!",
  "submit_emails": "test@example.com",
  "submit_email_subject": "Email from page",
  "submit_action": "message",
  "submit_success_message": "Thank you!",
  "submit_failure_message": "Invalid data has been submitted!",
  "fields": [{
    "id": "field_1389863908999",
    "type": "textfield",
    "title": "My only field in this form",
    "required": true,
    "field_size": "small",
    "placeholder": "This is placeholder"
  }]
}

Example response:

Status: 200 OK

{
  "id": 2,
  "title": "Form new name",
  "created_at": "2014-01-14T11:43:42.000Z",
  "updated_at": "2014-01-15T12:11:06.000Z",
  "url": "http://helloworld.voog.co/admin/api/forms/2",
  "tickets": "http://helloworld.voog.co/admin/api/forms/2/tickets",
  "content": {
    "id": 2,
    "name": "body",
    "position": 2,
    "created_at": "2014-01-14T11:43:42.000Z",
    "updated_at": "2014-01-14T11:43:42.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/3/contents/2"
  },
  "parent": {
    "id": 3,
    "title": "Contact",
    "type": "page",
    "created_at": "2014-01-14T11:43:37.000Z",
    "updated_at": "2014-01-14T11:43:37.000Z",
    "url": "http://helloworld.voog.co/admin/api/pages/3",
    "public_url": "http://helloworld.voog.co/contact"
  }
}

Parameters

Optional form parameters:

• title — form title (helps identify the form in admin interface).
• classname — optional class name for the form (default: null).
• recaptcha — Google reCAPTCHA v3 spam protection. Accepted values: null, true, false (default: null — controlled by site subscription (means true by default)).
• submit_label — label for form submit button (default: "Submit").
• submit_emails — email to where copy of the submitted form should be sent (default: null). Emails should be separated with comma (,) when more than one email are provided (e.g. info@test.com,sales@test.com).
• submit_email_subject — email subject. Used when submit_emails is set (default: "Posting from your website (*title*)").
• submit_action — what to do when form is submitted successfully. Accepted values: message, redirect (default: "message").
• submit_success_message — custom message after successful submit when submit_action="message" (default: "Form has been submitted. Thank you!").
• submit_failure_message — custom message after failed submit when submit_action="message" (default: "Invalid data has been submitted!").
• submit_success_address — full redirect url (e.g. "http://www.mysite.com/thank-you") after successful submit when submit_action="redirect" (default: null).
• fields — array of form fields. Replaces fields set whit new one. NB! When empty value is posted then all previously added fields are removed.
• include_details — if present, the response includes extra details, as the single form endpoint (default: false).

Required form field parameters:

• id — unique alphanumerical identificator for field (e.g. "field_1389863908999"). Used to match submitted form fields.
• type — field type. Accepted values:
  • textfield — common text fields.
  • textarea — multiline text area.
  • select — select options.
  • checkbox — checkbox.
  • radio — radio buttons.
  • file — file select.

Optional form field parameters:

• title — label for field (default: '').
• required — if true then required on form submit (default: null).
• classname — optional class name for form field wrapper element (default: null).
• format — optional format of of the field where type="textfield" (default: null). Accepted values:
  • email — validates submitted value against email format
  • website — validates submitted value against website.
• field_size — optional field size (default: null). Accepted values: small, medium and large. Used by types textfield and textarea.
• placeholder — placeholder text for inputs (default: null). Used by types textfield and textarea. Used by types textfield and textarea.
• rows — specifies the visible number of lines in a text area (default: null). Used by type textarea.
• multiple — if true then select field allows multi select (default: null). Used by type select.
• options — array of option values (e.g. ["Choice 1", "Choice 2"]) (default: []). Used by types select checkbox and radio.

Delete a form

DELETE /admin/api/forms/2

This request deletes the from from and it's related tickets the database.

Example request:

DELETE http://helloworld.voog.co/admin/api/forms/2

Example response:

Status: 204 No Content