Developers

Forms

Summary of forms endpoints

Related endpoints:

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"
    }
  }
]

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.

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"
  },
  "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
}

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"
  }
}

Parameters

Optional form parameters:

  • title - form title (helps identify the form in admin interface).
  • 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.

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