Forms API

Overview

• This API allows for external clients to retrieve form submissions that have been submitted by users.
• All requests to this API must be in HTTPS.
• JSON responses from the API have unspecified field orderings, and unspecified amounts of whitespace. Do not depend on the fields being in a certain order, or on whitespace being in a certain format.
• A testing server will be provided for you on request.

An example zip file for the 'download submissions' endpoint can be obtained here: example.zip.

Access Tokens

• username: The username of a user on the system who has either the 'administrator' role, or the 'manage forms' role.
• password: The password of the user

{
  "token": "<your access token>",
  "status": "SUCCESS"
}

{
  "token": null,
  "status": "<status>"
}

Listing Forms

• 'token' is an access token, obtained above.
• 'startIndex' will default to 0 if not specified. A maximum of 25 forms will be returned. Increase the 'startIndex' in increments of 25 to retrieve further results.

{
  "data": {
    "count": <count>,
    "elements": [
      {
        "name": "<form name>",
        "entityId": "<form entity ID>"
      },
      { ... }
    ]
  },
  "status": "SUCCESS"
}

• 'count' is the total number of available forms. For example, if there are 300 forms (only 25 of which will be provided in the response), then count will be 300.
• 'name' is the name of the form, as specified in the form editor.
• 'entityId' is a unique identifier that is assigned to a form when it is first created.

{
  "data": null,
  "status": "<status>"
}

• INVALID_TOKEN: The specified token does not exist
• EXPIRED_TOKEN: The specified token has expired
• INSUFFICIENT_PERMISSIONS: The user account associated with the token doesn't have the Administrator or Manage Forms role.
• INSECURE_REQUEST: Request was not made over HTTPS
• INVALID_REQUEST: The request was not in the expected format.
• INTERNAL_SERVER_ERROR: An error occurred while processing the request

Listing Form Answers

• 'token' works the same as above
• 'startIndex' works the same as covered above.
• 'formEntityId' restricts answers to the form with the specified entity ID. If not specified, then answers for all forms will be returned.

{
  "data": {
    "count": '<count>',
    "elements": [
      {
        "id": <id>,
        "host": "<host>",
        "referenceNumber": "<reference number>",
        "formEntityId": "<form entity id>",
        "formName": "<form name>",
        "dateCreated": 1437744175000
      }
    ]
  },
  "status": "SUCCESS"
}

• 'count' works as covered above.
• 'id' is a unique numeric identifier for the answer.
• 'host' is the host name the answer was submitted on.
• 'referenceNumber' is a unique reference number that is displayed to the user after an answer is submitted, and is displayed when viewing answers in the administrative side of the CMS.
• 'formEntityId' is the form entity ID of the form the answer is for
• 'formName' is the name of the form the answer is for
• 'dateCreated' is the date and time at which the answer was submitted, represented as the number of milliseconds since the Unix epoch.

{
  "data": null,
  "status": "<status>"
}

• INVALID_TOKEN: The specified token does not exist
• EXPIRED_TOKEN: The specified token has expired
• INSUFFICIENT_PERMISSIONS: The user account associated with the token doesn't have the Administrator or Manage Forms role.
• INSECURE_REQUEST: Request was not made over HTTPS
• INVALID_REQUEST: The request was not in the expected format.
• INTERNAL_SERVER_ERROR: An error occurred while processing the request

Downloading Form Answers

• 'token' works as it does in the above requests
• 'answerIds' is a list of answer IDs to download. Answer IDs can be obtained via the 'answers.html' endpoint covered above.

{
  "data": null,
  "status": "<status>"
}

• INVALID_TOKEN: The specified token does not exist
• EXPIRED_TOKEN: The specified token has expired
• INSUFFICIENT_PERMISSIONS: The user account associated with the token doesn't have the Administrator or Manage Forms role.
• INSECURE_REQUEST: Request was not made over HTTPS
• INVALID_REQUEST: The request was not in the expected format.
• INTERNAL_SERVER_ERROR: An error occurred while processing the request

Form Answer Zip File Structure

• /answers.json - All of the requested form answers are in here
• /documents/ - All files that the user uploaded via form file inputs are in here

[ <list of form answers> ]

{
    "id" : <id>,
    "dateCreated" : <date created>,
    "referenceNumber" : "<reference number>",
    "formEntityId" : "<form entity ID>",
    "inputAnswers" : [ <list of form input answers> ]
}

• 'id' is the id of the answer
• 'dateCreated' is the date and time on which the answer was submitted
• 'referenceNumber' is a unique reference number that is displayed to the user after an answer is submitted, and is displayed when viewing answers in the administrative side of the CMS.
• 'inputAnswers' is a list of the user's answers to the inputs in the form, for this particular form answer
  (note that 'form answer' refers to a form submission, whereas 'input answer' refers to a user's answer for an input in a submitted form)

{
    "name" : "<name>",
    "publicId" : "<public ID>",
    "answerType" : "<answer type>",
    "mappingId" : "<mapping id>",
    "inputType" : "<input type>",
    "repeaterPublicId" : "<repeater public ID>",
    "repeaterIndex" : "<repeater index>",
    <additional inputType specific fields>
}

• 'name' is the name of the form input this input answer is for (this is the label shown to the user)
• 'publicId' is a unique (within a form) identifier that is assigned when an input is created
• 'answerType' should be ignored
• 'mappingId' is similar to the publicId, except that it can be manually specified. Null if not specified.
• 'inputType' is the type of input this is. Covered below
• 'repeaterPublicId' is the public ID of the repeater this input is associated with. Null if not associated with a repeater
• 'repeaterIndex' : is the repeated index of this input. For example, if a repeater causes an input to be repeated twice, the second input answer will have a repeaterIndex of 1. Null if not associated with a repeater.

Text input types

All input answers of these types have a single additional field named 'value', which contains a string. The inputTypes that quality as text are as follows:

• 'TEXT' is an input that accepts a single line of text
• 'TEXTAREA' accepts multiple lines of text
• 'FULLNAME' is intended to hold a person's full name
• 'FIRSTNAME' is intended to hold a person's first name
• 'LASTNAME' is intended to hold a person's last name
• 'EMAIL' holds an email address. 
• 'PHONE' holds a phone number. There are no separators between digits.
• 'WHOLENUMBER' is an input that holds a number with no fractional component. 
• 'DOLLARAMOUNT' is an input that holds a number with an optional fractional component, intended to indicate a dollar amount.
• 'NUMBER' is an input that holds a number with an optional fractional component
• 'DATE' holds a date in the format 'yyyy-mm-dd'
• 'TIME' holds a time in the format 'h:mm AM/PM'
• 'REPEATERINPUT' holds a non-negative integer, which indicates how many times associated inputs should be repeated.

Address input type (inputType='ADDRESS')

• 'country' is a string that holds a two-letter country code (ISO 3166-1 alpha-2)
• 'state' holds a two-letter state abbreviation
• 'city' holds a city name (guaranteed to not be blank, but otherwise not validated)
• 'address1' holds the first address line (guaranteed to not be blank, but otherwise not validated)
• 'address2' holds the second address line (may be null)
• 'zip' holds a zip or postal code (validated)

{
    "name" : "<original image filename>",
    "fileName" : "<filename in documents directory>"
}

{
    "label" : "<label>",
    "price" : price,
    "sku" : "sku",
    "taxExempt" : true/false
}

{
    "name" : "<product name>",
    "totalQuantity" : <quantity>,
    "priceAnswers" : [ <list of price answers> ],
    "staticId" : "<static ID>"
}

{
    "name" : "<price option name>",
    "quantity" : <quantity>,
    "price" : <price>,
    "sku" : "sku"
}