Guides

Using the Online Actions API Endpoint

For more information on other methods to embed or integrate with Online Actions please see theOnline forms documentation page.

Overview

Online Actions collects form submissions via an unauthenticated POST to the endpoint for a particular form that is published. Our form rendering library, ActionTag, exists to make it easy to GET a form definition, render the form, prefill it, validate the inputs, and then submit it to the right endpoint. If one wishes to bypass ActionTag, it is possible to do the form POST yourself, but you will lose out on the benefits of the optimized UI, the prefilling, and the validation that ActionTag handles, and you will be responsible for doing that yourself.

Also of note, it is not possible to directly POST a submission for advocacy forms, nor can you use it for forms that process payment, as those will run afoul of our anti-fraud measures.

GET v1/Forms/{formId}

The formId is the alphanumeric string at the end of the published form URL. If the form URL is https://secure.everyaction.com/abc123, then abc123 is the formId.

To access the JSON definition of what the form is, issue a GET to https://secure.everyaction.com/v1/Forms/abc123 (or just load that URL in your browser). This will return all the fields configured on the form, along with some metadata about the form itself.

Here’s an example response using a demo with formId = 84UUCYB3x0y8zjqQYsDtKw2

{
   "tenantDisplayName":"ngpvan://van/EADEM/EADEM/1/52490",
   "submissionUrl":"https://secure.everyaction.com/v2/Forms/84UUCYB3x0y8zjqQYsDtKw2",
   "autoFastAction":false,
   "created":"2016-04-07 15:13:27Z",
   "fastAction":true,
   "form_elements":[
      {
         "name":"HeaderHtml",
         "type":"markup",
         "markup":"<h1>Please join us.</h1>"
      },
      {
         "name":"submitForm",
         "type":"submit",
         "value":"Submit"
      },
      {
         "name":"ContactInformation",
         "type":"fieldset",
         "title":"Contact Information",
         "children":[
            {
               "name":"FirstName",
               "type":"textfield",
               "title":"First Name",
               "queryString":"fn",
               "required":true,
               "maxlength":20
            },
            {
               "name":"LastName",
               "type":"textfield",
               "title":"Last Name",
               "queryString":"ln",
               "required":true,
               "maxlength":25
            },
            {
               "name":"AddressLine1",
               "type":"textfield",
               "title":"Street Address",
               "queryString":"add1",
               "required":true,
               "maxlength":99
            },
            {
               "name":"City",
               "type":"textfield",
               "title":"City",
               "queryString":"ci",
               "required":true,
               "maxlength":25
            },
            {
               "name":"StateProvince",
               "type":"select",
               "title":"State",
               "queryString":"st",
               "required":true,
               "options":"table_stateprovinces"
            },
            {
               "name":"PostalCode",
               "type":"textfield",
               "title":"Zip Code",
               "queryString":"pc",
               "required":true,
               "maxlength":10,
               "validation":"postalCode"
            },
            {
               "name":"HomePhone",
               "type":"international_phone",
               "title":"Home Phone",
               "default_country_code":"US",
               "queryString":"hp",
               "required":false,
               "validation":"phone",
               "options":"table_countries"
            },
            {
               "name":"EmailAddress",
               "type":"textfield",
               "title":"Email",
               "queryString":"em",
               "required":true,
               "maxlength":100,
               "validation":"email"
            },
            {
               "name":"YesSignMeUpForUpdatesForBinder",
               "type":"hidden",
               "value":true,
               "queryString":"ae"
            },
            {
               "name":"PersonalUrl",
               "type":"textfield",
               "queryString":"PersonalUrl",
               "required":false
            },
            {
               "name":"TrackingPixel",
               "type":"markup",
               "markup":"<img alt='' src='https://secure.everyaction.com/v1/Track/84UUCYB3x0y8zjqQYsDtKw2' style='display:none'/>"
            }
         ]
      }
   ],
   "formId":2529,
   "metadata":{
      "layoutStyle":"standard",
      "displayConfirmationMessage":true,
      "deactivationHtmlContent":"<img alt='' src='https://secure.everyaction.com/v1/Track/84UUCYB3x0y8zjqQYsDtKw2' style='display:none'/>",
      "columns":1,
      }
   },
   "status":"Published",
   "title":"Social share example",
   "name":"Social share example",
   "type":"SignupForm",
   "updated":"2016-04-29 19:56:29Z",
   "url":{
      "full":"https://secure.everyaction.com/v1/Forms/84UUCYB3x0y8zjqQYsDtKw2",
      "base":"https://secure.everyaction.com/",
      "slug":""
   },
   "shortCode":"84UUCYB3x0y8zjqQYsDtKw2"
}

GET v1/Track/{formId}

This endpoint registers a form view for conversion tracking purposes. If you are POSTing directly to the v1/Forms/{formId} endpoint, you probably want to consider including markup that loads this tracking pixel somewhere in your page (otherwise you will end up with a conversion rate of over 100%).

Here’s the example markup that our ActionTag forms use, as one way you could achieve this in your own implementation:

<div class="at-markup TrackingPixel" style="display: none;">v <img alt="" src="https://secure.everyaction.com/v1/Track/abc123" style="display:none"> </div>

POST v1/Forms/{formId}

This endpoint allows you to create a POST with the fields you wish to process as a form submission. In addition to all of the required fields from the form definition JSON, the type must also be included. It is in the form definition, but it can be one of EventForm, PetitionForm, SignupForm, or VolunteerForm. Again you cannot use this for Advocacy forms, nor should you use it for forms that process payment (i.e. Contribution forms or ticketed event forms that process payment).

The request must use Content-Type=application/x-www-form-urlencoded; charset=UTF-8; with key/value pairs, the key of each field being the name attribute from the form definition. You can look in the network tab of your browser during a form submission to see an example of ActionTag making that POST. Here’s an example:

AddressLine1=1101 15th St NW&AddressLine2=Ste 500&City=Washington&[email protected]&FirstName=Jane&LastName=Casey&PostalCode=20005&StateProvince=DC&YesSignMeUpForUpdatesForBinder=true&type=SignupForm}

A successful form post returns the resultCode of Success as well as the page response and a timestamp of the submission. Example:

{
   "page":{
      "confirmationActionType":"DisplayContent",
      "confirmationPageContent":"<p>Dear Rob,</p>\r\n\r\n<p>&nbsp;</p>\r\n\r\n<p>Thank you for joining our organization.</p>\r\n\r\n<p><span style=\"font-weight:bold\">Contact Information:<br />\r\nRob Winikates<br />\r\n104 Woodstock St<br />\r\nSomerville&nbsp; MA&nbsp;02144</span></p>\r\n\r\n<p>&nbsp;</p>\r\n\n<div class=\"fb-share-button\" data-href=\"https://secure.everyaction.com/84UUCYB3x0y8zjqQYsDtKw2\" data-layout=\"button_count\"></div>"
   },
   "response":{
      "submissionId":"540284",
      "trackingId":"7d853479-7b39-4398-9f7d-63254cc307fd",
      "fullName":"Rob Winikates",
      "contributionDateTimeStamp":"0001-01-01T00:00:00+00:00"
   },
   "errors":[
      
   ],
   "resultCode":"Success"
}

Updated over 1 year ago