Skip to main content

Help Docs

doForms REST API Guide

Judah Sali
  • Updated

The doForms REST API has a variety of uses:

  • Get submission data
  • Get lists of users and devices
  • Send dispatches
  • Manage lookups and lookup data
  • Get lists of customers if you are a reseller

View the detailed REST API documentation (in OpenAPI format) by selecting Manage > Integrations > REST API documentation (OpenAPI).

The doForms REST API documentation can be found here.

The doForms SOAP API documentation can be found here.

Java sample code can be found here.

C# sample code can be found here.

The doForms REST API is available to accounts on the Premium plan.

 

Authentication

Unless noted otherwise, all requests must include an Authorization header with the value "Bearer [token]".

User token

Obtain a user token by posting web user credentials to the /tokens/user endpoint. Requests with a user token will inherit the rights of the user account.

Web service token

Obtain a web service token by posting web service credentials to the /tokens/webservice endpoint. Requests with a web service token will have access to the project and form of the web service.

Web service

Build a static web service token by combining a web service ID and web service password separated by a colon.

Example:

  • Web service ID: acme$$1234$$Published$$5678
  • Password: mypassword
  • Token: acme$$1234$$Published$$5678:mypassword
  • Authorization header: "Bearer acme$$1234$$Published$$5678:mypassword"

Requests with a static web service token will have access to the project and form of the web service at these endpoints:

Reseller token

Obtain a reseller token by posting reseller credentials to the /tokens/reseller endpoint.

Requests with a reseller token have access to account management endpoints for the customers of the reseller:

Get submission data

1. Get submission identifiers

There are two ways to get the identifiers of the submissions to retrieve:

  • Query for submission keys by date range or other criteria. 
  • Generate submission ids based on an incrementing index. Use this approach when the goal is to retrieve all submissions in a form.

Query for submission keys

  1. Specify the project and form to query in one of two ways:
    • Include formKey & projectKey in the query parameters:
      GET /submissions?formKey=abc123&projectKey=def456
    • Or, use webservice authentication, which establishes the project and form to use.
  2. Add additional query parameters.
    For example, this will query for submissions received at the server in a 24 hour range (using webservice authentication): 
    GET /submissions?receiveTime=2019-09-15T13:08:36&@receiveTime=2019-09-16T13:08:36

See the documentation of the GET /submissions endpoint for more query details.

Generate submission ids

  1. Get the most recent submission id for the form at 
    GET /forms/{keyOrIdOrName/latest
  2. Generate submission ids by updating the final segment of the submission id as an incrementing index that starts at 1. For example if the most recent submission id is
    acmeinc$$12345$$Published&&9
    There are 9 possible submission ids between 
    acmeinc$$12345$$Published&&1
    and 
    acmeinc$$12345$$Published&&9
  3. Note that some ids may return an error instead of a submission:
    • If the submission has been deleted.
    • If the id was reserved by the app but the submission was never uploaded.
    • If webservice authentication is used and the submission belongs to a different project than the webservice.

2. Retrieve submissions

Once you have submission identifiers, your submission data can be retrieved in one of two formats:

  • Standard submission format (submission)
  • Custom submission format (data)

Standard submission format (submission)

Use this approach if you are writing code that will continue to work without requiring changes when form definitions are added or updated.

Retrieve submissions at either of these endpoints:

GET /submissions/{keyOrId}
GET /forms/{keyOrIdOrName}/submissions/{keyOrIdOrIndex}

Submission data is returned in a standard format that is more flexible than the custom format, but may be more difficult to understand.

For example, if a form has a text field with a data name of

My_Text_Field

The submission JSON will look like this (some properties omitted):

{
  "key":"sQXR6U2z3Az3qxA987NgFmHsDiiikW",
  "fields":[
    {
      "name":"My_Text_Field",
      "data":"text",
      "type":"text",
      "text":"What the user entered"
    }
  ]
}

See these examples of how to model the form and submission structure and deserialize the data:

Java sample code

C# sample code

See the detailed documentation of the GET /submissions/{keyOrId} endpoint for more details.

Custom submission format (data)

Use this approach if you are writing code that is specific to your form definition. New or updated form definitions will require code changes.

Retrieve submissions at

GET /forms/{keyOrIdOrName}/data/{keyOrIdOrIndex}

Submissions retrieved at this endpoint will use the field data name as the JSON property name. 

For example, if a form has a text field with a data name of

My_Text_Field

The submission JSON will look like this (some properties omitted):

{
  "key":"sQXR6U2z3Az3qxA987NgFmHsDiiikW",
  "data":{
    "My_Text_Field":"What the user entered"
  }
}

 

The archived REST API docs can be found here:

https://doforms.atlassian.net/wiki/spaces/PD/pages/380272662/doForms+REST+Web+Service+API

Related articles