Documentation has moved

The doForms REST API documentation has moved to https://mydoforms.appspot.com/openapi/openapi.html

The doForms REST API provides integration with the doForms system.

The doForms SOAP API documentation can be found here.

URL

The doForms REST API is located at

https://api-dot-mydoforms-hrd.appspot.com/api/v2

Sample Code

Java REST Sample Code

C# REST Sample Code

Authorization

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

cURL	--header 'Authorization: Bearer [token]'
jQuery	"headers": {"Authorization": "Bearer [token]"}
Python	headers = {'Authorization': 'Bearer [token]'}
Java	httpURLConnection.setRequestProperty("Authorization", "Bearer [token]");
C#	httpClient.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", [token]);

There are four options for obtaining a token:

User token

Obtain a user token by posting web user credentials to the /tokens/user endpoint described below. 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 described below. Requests with a web service token will have access to the project and form of the web service.

Web service

Build a static token by combining a web service ID and web service password separated by a colon. Requests with a static token will have access to the project and form of the web service.

Example:

Web service ID: acme$$1234$$Published$$5678
Password: mypassword
Token: acme$$1234$$Published$$5678:mypassword

Reseller token

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

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

GET /accounts
GET /accounts/{key or code}
PUT /accounts/{key or code}
GET /devices?account={key or code}
GET /devices/{key or number}?account={key or code}
GET /users?account={key or code}
GET /users/{key or email}?account={key or code}

Endpoints

GET /accounts?

Response

Notes

[
  {
    "key": "abc123",
    "code": "acmeinc",
    "administrator": {
      "email": "me@me.com",
      "firstName": "Bob",
      "lastName": "Smith",
      "workPhone": "1111111111"
    },
    "branded": true,
    "credits": 10,
    "licenses": 1,
    "name": "Acme Inc Corp Ltd Pty",
    "plan": {
      "code": "pre02",
      "name": "Premium"
    },
    "status": "Paid",
    "active": true
  },
  {
    "key": "abc124",
    "code": "democo",
    "administrator": {
      "email": "me@me.com",
      "firstName": "Bob",
      "lastName": "Smith Jr",
      "workPhone": "+5551231234"
    },
    "branded": true,
    "credits": 10,
    "licenses": 1,
    "name": "Test company",
    "plan": {
      "code": "dem02",
      "name": "Demo"
    },
    "status": "Canceled",
    "active": false
  }
]

Query customer accounts.

Requires reseller authentication.

Possible query fields:
- administrator.email

GET /accounts/current

Response

Notes

{
  "key": "abc123",
  "code": "acmeinc",
  "administrator": {
    "email": "me@me.com",
    "firstName": "Bob",
    "lastName": "Smith",
    "workPhone": "1111111111"
  },
  "branded": true,
  "credits": 10,
  "licenses": 1,
  "name": "Acme Inc Corp Ltd Pty",
  "plan": {
    "code": "pre02",
    "name": "Premium"
  },
  "status": "Paid",
  "active": true
}

Returns information about the current account.

Requires user authentication.

GET /accounts/{key or code}

Response

Notes

{
  "key": "abc123",
  "code": "acmeinc",
  "administrator": {
    "email": "me@me.com",
    "firstName": "Bob",
    "lastName": "Smith",
    "workPhone": "1111111111"
  },
  "branded": true,
  "credits": 10,
  "licenses": 1,
  "name": "Acme Inc Corp Ltd Pty",
  "plan": {
    "code": "pre02",
    "name": "Premium"
  },
  "status": "Paid",
  "active": true
}

Get the account.

Requires reseller authentication.

PUT /accounts/{key or code}

Body

Notes

{
  "active": true
}

Update the account.

active - Set to true to activate the account, false to deactivate the account. Requires reseller token authentication.
requires reseller authentication.

GET /activity?

Response

Notes

[
  {
    "key": "act124",
    "submissionKey": "abc123",
    "projectKey": "pqr123",
    "formKey": "fgh123",
    "receiveTime": "2019-08-20T15:35:19.139-04:00",
    "type": "update",
    "submissionId": "acme$$12345$$Published&&1",
    "submissionName": "My name | 3",
    "projectName": "Main Project",
    "formName": "First Form v1",
    "userId": "me@me.com",
    "userName": "My Name"
  },
  {
    "key": "act123",
    "submissionKey": "abc123",
    "projectKey": "pqr123",
    "formKey": "fgh123",
    "receiveTime": "2019-08-20T14:38:54.896-04:00",
    "type": "new",
    "submissionId": "acme$$12345$$Published&&1",
    "submissionName": "My name | 3",
    "projectName": "Main Project",
    "formName": "First Form v1",
    "userId": "5551231234",
    "userName": "Device one"
  }
]

Returns all submission activity the user has access to.

Required query parameters:
- @beginTime - ISO formatted date/time inclusive
- @endTime - ISO formatted date/time exclusive
Requires user authentication.
To query activity by device, form or project, see the these endpoints:
- GET /devices/{key or number}/activity?
- GET /forms/{key or id}/activity?
- GET /projects/{key}/activity?

GET /devices?

Response

Notes

[
  {
    "key": "def123",
    "name": "Device one",
    "email": "me@me.com",
    "number": "5551231234",
    "teamKey": "tuv123"
  },
  {
    "key": "def234",
    "name": "Device two",
    "email": "you@you.com",
    "number": "5551234321",
    "teamKey": "tuv123",
    "lastTrack": {
      "date": "2018-06-29T11:56:26.000Z",
      "offset": -240,
      "status": "MOVING",
      "position": {
        "accuracy": 20.885,
        "altitude": 304.899,
        "latitude": 34.101222,
        "longitude": -84.0015005
      },
      "velocity": {
        "bearing": 31.2198,
        "direction": "NNE",
        "distance": 489.332,
        "speed": 7.6032
      }
    }
  }
]

Returns all devices the user has access to.

Get a more limited list of devices at /teams/{key}/devices.
If the device has GPS tracking enabled, the last track received is returned in lastTrack.
Optional query parameters: latitude, longitude
- If a device has a lastTrack node, return the distance to the provided latitude and longitude in lastTrack.distanceToTarget.
Requires user authentication.

GET /devices/{key or number}

Response

Notes

{
  "key": "def123",  
  "number": "5551231234",
  "name": "Device one",
  "email": "me@me.com",
  "teamKey": "tuv123"
}

Returns the requested device.

If number = "Available" the device license has not been assigned to a device.
Optional query parameters: latitude, longitude
- If a device has a lastTrack node, return the distance to the provided latitude and longitude in lastTrack.distanceToTarget.
Requires user authentication.

GET /devices/{key or number}/activity?

Response

Notes

[
  {
    "key": "act123",
    "submissionKey": "abc123",
    "projectKey": "pqr123",
    "formKey": "fgh123",
    "receiveTime": "2019-08-20T14:38:54.896-04:00",
    "type": "new",
    "submissionId": "acme$$12345$$Published&&1",
    "submissionName": "My name | 3",
    "projectName": "Main Project",
    "formName": "First Form v1",
    "userId": "5551231234",
    "userName": "Device one"
  }
]

Returns all submission activity for a device that the user has access to.

Required query parameters:
- @beginTime - ISO formatted date/time inclusive
- @endDate - ISO formatted date/time exclusive
Requires user authentication.
To query all activity, see the /activity? endpoint.

POST /dispatches

Body

Notes

Request

{
  "ownerId": "5551231234",
  "fields": [
    { "name": "Name",
      "text": "My name" 
    },
    { "name": "Choose",
      "text": "3"
    },
    { "name": "Today_s_date",
      "date": "2019-08-19"
    },
    { "name": "Number",
      "integer": 25
    },
    { "name": "Customer_Table",
      "rows": [
        {"fields": [
          { "name": "Customer_ID",
            "text": "32-151"
          },
          { "name": "Customer_name",
            "text": "ABC Companies"
        }]},
        {"fields": [
          { "name": "Customer_name",
            "text": "Global Industries"
          },
          { "name": "Customer_ID",
            "text": "44-158"
          }]
        }]
      }
    }]
}

Add a new dispatch.

ownerId - (optional) Set the mobile number to receive the dispatch. If no mobile number is assigned, the dispatch will be set to Pending status.
fields - An array of fields to populate. All fields are optional.
- Follow the structure of fields and rows of the form as retrieved from /dispatches/{key} or /submissions/{key}.
- Only the "name" and the value properties ("text", "integer", "date", etc.) are required for each field.
Requires webservice authentication.

200 OK

{
  "code": 200,
  "key": "rst123",
  "ownerKey": "def123",
  "status": "Sent"
}

code - 200 for success.
key - The key of the dispatch. Retrieve the full dispatch at /dispatches/{key}.
ownerKey - The key of the device that will receive the dispatch if the ownerId field was populated.
status - Either "Sent" or "Pending"

Error

{
  "code": 401,
  "message": "HTTP 401 Unauthorized"
}

code - The HTTP code of the error.
message - The error message.

GET /dispatches?

Response	Notes
[ { "key": "rst123", "id": "acme$$12345$$Published&&1" }, { "key": "rst124", "id": "acme$$12345$$Published&&2" } ]	Returns dispatch identifiers that match a query. See /submissions? for more details. Requires user or webservice authentication.

DELETE /dispatches/{key or id}

Response

Notes

200 OK

Delete a dispatch.

Any related submission can be deleted at /submissions/{key or id}.
Requires user or webservice authentication.

GET /dispatches/{key or id}?

Response

Notes

{ "key": "abc123",
  "id": "acme$$12345$$Published&&1",
  "name": "My name | 3",
  "type": "dispatch",
  "formKey": "fgh123",
  "formName": "First Form v1",
  "formVersion": 1.0, 
  "offset": -240,
  "ownerId": "5551231234",
  "ownerName": "Device one",
  "ownerType": "device",
  "projectKey": "pqr123",
  "receiveTime": "2019-08-20T14:38:54.896-04:00",
  "sourceId": "me@me.com",
  "sourceName": "My Name",
  "sourceType": "user",
  "status": "On site",
  "statusTime": "2019-08-20T15:30:24.052-04:00",
  "systemStatus":"Viewed",
  "timezone": "Eastern Daylight Time",
  "updateTime": "2019-08-20T15:35:19.139-04:00",
  "updateUser": "me@me.com", 
  "fields": [
    { "name": "Name",
      "data": "text",
      "type": "text",
      "text": "My name" 
    },
    { "name": "Choose",
      "data": "text",
      "type": "choose_one",
      "text": "3"
    },
    { "name": "Form_Title",
      "data": "text",
      "type": "label",
      "text": "Form_Title"
    },
    { "name": "Today_s_date",
      "data": "date",
      "type": "date_time",
      "date": "2019-08-19T00:00:00.000Z"
    },
    { "name": "Number",
      "data": "integer",
      "type": "numeric",
      "integer": 25
    },
    { "name": "Customer_Table",
      "data": "rows",
      "type": "table",
      "rows": [
        { "index": 0,
           "fields": [
            { "name": "Customer_ID",
              "data": "text",
              "type": "lookup",
              "text": "32-151"
            },
            { "name": "Customer_name",
              "data": "text",
              "type": "text",
              "text": "ABC Companies"
            } ]
        },
        { "index": 1,
          "fields": [
            { "name": "Customer_name",
              "data": "text",
              "type": "text",
              "text": "Global Industries"
            },
            { "name": "Customer_ID",
              "data": "text",
              "type": "lookup",
              "text": "44-158"
            } ]
        } ]
    }
}

Returns the data of a dispatch record by key or id.

See /submissions/{key} endpoint for more details.
Dispatch specific fields:
- submissionKey - Populated if the dispatch has been converted into a submission.
- systemStatus - Same as status, but will never be set to a user defined status value.
Requires user or webservice authentication.

POST /files/{file name}

Response

Notes

{
  "key": "fil123",
  "name": "My lookup.csv",
  "size": 2276338,
  "md5": "md123==",
  "createTime": "2019-07-18T19:22:40.958Z",
  "updateTime": "2019-07-18T19:52:38.600Z",
  "expireTime": "2019-08-17T19:52:38.600Z"
}

Upload a file that can be used as a lookup table or can be sent as part of a dispatch.

Requires user authentication.
Include the file name (including extension) in the path.
Set the Content-Type header to "application/octet-stream".
Set the body to the binary file content.
If the same file name is used again, the existing file will be overwritten.
Files are automatically deleted after 30 days.
key - The key identifier of the file.
name - The name of the file. Any invalid characters in the original file name will be replaced here.
size - The file size in bytes.
md5 - The MD5 hash of the received file.
expireTime - The approximate time the file will be automatically deleted.

Files larger than 32MB will return a 413 error.

To upload a large file, leave the body empty. Two new properties will be returned:

putUrl - Send a PUT request to this URL with the file content as the body. Expires after 60 minutes.
contentType - Use this value in the Content-Type header of the PUT request.

GET /file/{key or file name}

Response

Notes

{
  "key": "fil123",
  "name": "My picture.jpg",
  "size": 2276338,
  "md5": "md123==",
  "createTime": "2019-07-18T19:22:40.958Z",
  "updateTime": "2019-07-18T19:52:38.600Z",
  "expireTime": "2019-08-17T19:52:38.600Z"
}

Get information about a file.

Requires user authentication.

DELETE /file/{key or file name}

Notes

Delete a file.

Requires user authentication.
Files are automatically deleted after 30 days.

GET /forms

Response

Notes

[
  {
    "key": "fgh123",
    "id": "acme$$12345$$Published",
    "name": "First Form v1",
    "displayName": "First Form",
    "createTime": "2019-08-20T16:55:20.130Z",
    "createUser": "me@me.com",
    "updateTime": "2019-08-20T17:55:21.799Z",
    "updateUser": "me@me.com",
    "version": 1.01
  },
  {
    "key": "fgh234",
    "id": "acme$$23456$$Published",
    "name": "Second Form",
    "displayName": "Second Form",
    "createTime": "2019-07-20T16:55:20.130Z",
    "createUser": "me@me.com",
    "updateTime": "2019-07-20T17:55:21.799Z",
    "updateUser": "me@me.com",
    "version": 1.0
  }
]

Returns the first 1,000 forms published in projects the user or web service has access to.

Requires user or webservice authentication.
If the account contains a large number of forms, the /projects/{key}/forms endpoint is recommended.
key - The key identifier of the form.
id - The human readable identifier of the form.
name - The published name of the form. Required to be unique and can not be changed.
displayName - The form name displayed on the device. Does not have to be unique.
createTime - The time in UTC the form was created.
createUser - The username of the user that created the form.
updateTime - The time in UTC the form was last updated.
updateUser - The username of the user that last updated the form.
version - Increments with each change in the form definition.

GET /forms/{key or id}

Response

Notes

{
  "key": "fgh123",
  "id": "acme$$12345$$Published",
  "name": "First Form v1",
  "displayName": "First Form",
  "createTime": "2019-08-20T16:55:20.130Z",
  "createUser": "me@me.com",
  "updateTime": "2019-08-20T17:55:21.799Z",
  "updateUser": "me@me.com",
  "version": 1.01,

  "fields": [
    { "name": "Form_Title",
      "data": "text",
      "type": "label",
      "options": {
        "label": { "en": "First Form" },
        "level": 0 }
    },
    { "name": "First_Name",
      "data": "text",
      "type": "text",
      "options": {
        "label": { "en": "First Name" },
        "hint": { "en": "Please enter your first name" },
        "level": 0 }
    },
    { "name": "Number",
      "data": "integer",
      "type": "numeric",
      "options": {
        "label": { "en": "Number" },
        "level": 0 }
    },
    {
      "name": "Today_s_date",
      "data": "date",
      "type": "date_time",
      "options": {
        "label": { "en": "Today's date" },
        "level": 0 },
      "value": "today"
    },
    { "name": "Choose",
      "data": "text",
      "type": "choose_one",
      "choices": [
        { "text": "1",
          "label": { "en": "Option 1" }
        },
        { "text": "2",
          "label": { "en": "Option 2" }
        },
        { "text": "3",
          "label": { "en": "Option 3" }
        }
      ],
      "options": {
        "label": { "en": "Choose" },
        "level": 0 },
      "text": "2"
    },
    { "name": "Customer_Table",
      "data": "rows",
      "type": "table",
      "options": {
        "label": { "en": "Customer Table" },
        "level": 0,
        "rows": 5 },
      "rows": [
        { "index": 0,
          "fields": [
            { "name": "Customer_ID",
              "data": "text",
              "type": "lookup",
              "options": {
                "label": { "en": "Customer ID" },
                "level": 1 }
              },
            { "name": "Customer_name",
              "data": "text",
              "type": "text",
              "options": {
                "label": { "en": "Customer name" },
                "level": 1 }
              }]
        }]
    },
    { "name": "Signature",
      "data": "blob",
      "type": "signature",
      "options": {
        "label": { "en": "Signature" },
        "level": 0 }
    },
    { "name": "Picture",
      "data": "blob",
      "type": "image",
      "options": {
        "label": { "en": "Picture" },
        "level": 0 }
    },
    { "name": "Save_and_send",
      "type": "action",
      "options": { 
        "level": 0 }
    }
  ]
}

Returns the form definition by either the key or the id of the form.

See the /forms endpoint for a description of the first nine fields.
Requires user or webservice authentication.
fields - The array of all fields defined in the form:
- name - The data name of the field. Required to be unique and can not be changed.
- data - The type of data stored and the name of the field where the data can be found in the /submissions endpoint. Will be null if the field stores no data.
- type - The type of control presented to the user.
- options - Additional properties of the field:
  - comment - True if this is a questionnaire field that includes comments.
  - commentLabel - The label used for questionnaire comments.
  - format - Custom format string.
  - label - The title of the field shown to the user.
  - hint - The hint shown to the user.
  - level - The level of the field in the hierarchy of fields. E.g. a field with level 1 would be a child of a field with level 0.
  - prefix - Custom prefix applied to the data.
  - rows - The number of rows a table or repeatable field can have. Variable rows is indicated by -1.
- choices - The list of choices for choose type fields:
  - text - The value that will be stored.
  - label - The value displayed to the user.
- fields - An array of child fields contained inside this field. Grid and questionnaire fields can contain other fields.
- rows - An array with a single row that includes the fields contained inside this field. Table and repeatable fields can contain rows.
Default values
- Any default value is stored in a property that matches the data property. E.g. the default value of the Choose field is stored in the text property.
- Date and time fields may have a default value in the value property, e.g. "today".
See the /submissions/{key} endpoint for all possible values of the data property.
Possible values for the type property:
- action
- approval
- attachment
- audio
- autonumber
- barcode
- bluetooth_le
- button
- button_grid
- calculation
- choose_one
- choose_multiple
- counter
- date_time
- email
- fax
- forward
- grid
- image
- instruction
- label
- location
- lookup
- nfc
- numeric
- page
- payment
- pod
- questionnaire
- repeat
- retrieve
- schedule
- score
- score_summary
- signature
- sketch
- table
- text
- trends
- video
- viewer

GET /forms/{key or id}/activity?

Response

Notes

[
  {
    "key": "act124",
    "submissionKey": "abc123",
    "projectKey": "pqr123",
    "formKey": "fgh123",
    "receiveTime": "2019-08-20T15:35:19.139-04:00",
    "type": "update",
    "submissionId": "acme$$12345$$Published&&1",
    "submissionName": "My name | 3",
    "projectName": "Main Project",
    "formName": "First Form v1",
    "userId": "me@me.com",
    "userName": "My Name"
  },
  {
    "key": "act123",
    "submissionKey": "abc123",
    "projectKey": "pqr123",
    "formKey": "fgh123",
    "receiveTime": "2019-08-20T14:38:54.896-04:00",
    "type": "new",
    "submissionId": "acme$$12345$$Published&&1",
    "submissionName": "My name | 3",
    "projectName": "Main Project",
    "formName": "First Form v1",
    "userId": "5551231234",
    "userName": "Device one"
  }
]

Returns all submission activity for a form that the user has access to.

Requires user or webservice authentication.
Required query parameters:
- @beginTime - ISO formatted date/time inclusive
- @endDate - ISO formatted date/time exclusive
Requires user token authentication.
To query all activity, see the /activity? endpoint.

GET /forms/{key or id}/fields

Response

Notes

[
  { "name": "Form_Title",
    "data": "text",
    "type": "label",
    "options": {
    "label": { "en": "First Form" },
      "level": 0 }
  },
  { "name": "Name",
    "data": "text",
    "type": "text",
    "options": {
      "label": { "en": "Name" },
      "level": 0 }
  }
]

Returns the fields array for the selected form by key or by id.

Requires user or webservice authentication.
See the /forms/{key} endpoint for more detail.

GET /forms/{key or id}/latest

Response

Notes

{
  "id": "acme$$12345$$Published&&19"
}

Returns information about the last submission generated for the form. Use to identify which submissions can be retrieved at /submissions/{id}.

id - The last submission id generated for the form.
The final part of the submission id is an auto incrementing integer that begins at 1.
In this example, generate expected submission ids by replacing the 19 with the range of numbers from 1 to 19. (e.g. acme$$12345$$Published&&1, acme$$12345$$Published&&2, etc.)
There may be gaps in the range of id values if a submission has been deleted, or if an id was reserved but the submission was not completed.
The auto incrementing id number is shared across projects. When using web service authentication, if a submission requested at /submissions/{id} is a in a different project than the web service, a 401 error will be returned.

GET /forms/{key or id}/projects

Response

Notes

[
  {
    "key": "pqr123",
    "name": "Main Project"
  },
  {
    "key": "pqr234",
    "name": "Second Project"
  }
]

Returns all projects the requested form is assigned to.

Requires user or webservice authentication.

GET /groups

Response

Notes

[
  {
    "key": "ghi123",
    "name": "Group One"
  },
  {
    "key": "ghi124",
    "name": "Group Two"
  }
]

Returns all groups in the account.

Requires user authentication.
Web users can be assigned to a group.

GET /groups/{key}

Response

Notes

{
  "key": "ghi123",
  "name": "Group One"
}

Returns the requested group by key.

Requires user authentication.

GET /groups/{key}/users

Response

Notes

[
  {
    "key": "uvw124",
    "email": "you@you.com",
    "firstName": "Your",
    "lastName": "Name",
    "groupKey": "ghi123",
    "workPhone": "555 123 1235"
  }
]

Returns all users assigned to the requested group.

Requires user authentication.
See /users for more detail.

GET /lookups

Response

Notes

[
  {
    "key": "lmn123",
    "name": "Customer_List",
    "description": "List of customers",
    "useForm": false,
    "encrypt": false,
    "version": 2,
    "createTime": "2021-07-09T21:01:47.037Z",
    "createUser": "you@you.com",
    "updateTime": "2021-07-09T23:19:02.132Z",
    "updateUser": "you@you.com"
  },
  {
    "key": "lmn124",
    "name": "Lookups_Parts_Form",
    "description": "",
    "useForm": true,
    "useFilter": false,    
    "formKey": "fgh123",
    "projectKey": "pqr123",
    "update": true,
    "encrypt": false,    
    "version": 70,
    "createTime": "2021-05-04T20:24:31.952Z",
    "createUser": "you@you.com",
    "updateTime": "2021-07-09T23:19:02.132Z",
    "updateUser": "you@you.com"
  }
]

Return all lookups in the account.

Requires user authentication.
useForm - true if the lookup is a form based lookup.
useFilter - true if a form based lookup has a filter applied.
update - true if the form based lookup updates automatically as submissions are updated.
encrypt - true if the lookup is encrypted.
version - increments each time the lookup is updated.

POST /lookups

Body

Notes

Request

{
  "name": "Customer_List",
  "description": "List of customers",
  "finalize": true,
  "encrypt": false,
  "columns": [
    {
      "name": "Customer code",
      "caption": "The customer code"
    },
    {
      "name": "Customer name"
    }
  ],
  "rows":[
    {"Customer code": "ABC123", "Customer name": "ABC Customer"},
    {"Customer code": "DEF456", "Customer name": "DEF Customer"}
  ]
}

Add a new lookup.

Requires user authentication.
Form based lookups can not be added via the API.
name - required. If the name provided duplicates the name of an existing lookup, the name will be made unique.
description - optional.
finalize - optional. True if all rows are included in this request. The lookup will be marked as ready to deliver to devices.
encrypt - optional. True if the lookup should be encrypted at rest. The account must have field encryption enabled to use encryption.
columns - required. The columns in the lookup. Columns can not be changed after the lookup is created.
- name - required.
- caption - optional.
rows - optional. The first set of rows in the lookup. The field names must match the names specified in columns. Add additional rows at PUT /lookups/{key} or POST /lookups/{key}/rows.
- Property names must match the names defined in the columns.
fileName - optional. The name of a file previously uploaded at POST /files/{fileName}.
fileKey - optional. The key of a file previously uploaded at POST /files/{fileName}. If fileName or fileKey is specified, rows will be ignored. The file must be either CSV or xlsx format and the columns in the file must match the columns specified in this request. Add additional rows from a file at PUT /lookups/{key}.
fileHasHeaders - optional. Set to false if the file to import does not have a header row.

200 OK

{
  "code": 200,
  "count": 2,
  "lookup": {
    "key": "lmn123",
    "name": "Customer_List",
    "description": "List of customers",
    "useForm": false,
    "encrypt": false,
    "version": 1,
    "createTime": "2021-07-09T21:01:47.037Z",
    "createUser": "you@you.com",
    "updateTime": "2021-07-09T21:01:47.037Z",
    "updateUser": "you@you.com",
    "columns": [
      {
        "name": "Customer code",
        "caption": "The customer code"
      },
      {
        "name": "Customer name"
      }
    ]
  }
}

count - The number of rows added in this request.
lookup - The lookup that was added.

GET /lookups/{key}

Response

Notes

{
  "key": "lmn124",
  "name": "Lookups_Parts_Form",
  "description": "",
  "useForm": true,
  "useFilter": false,
  "formKey": "fgh123",
  "projectKey": "pqr123",
  "update": true,
  "encrypt": false,
  "version": 70,
  "createTime": "2021-05-04T20:24:31.952Z",
  "createUser": "you@you.com",
  "updateTime": "2021-07-09T23:19:02.132Z",  
  "updateUser": "you@you.com",  
  "columns": [
    {
      "name": "Part_Number",
      "caption": "Part number"
    },
    {
      "name": "Part_Name",
      "caption": "Part name"
    }
  ]
}

Return a lookup.

Requires user authentication.
columns - the list of columns in the lookup.

PUT /lookups/{key}

Body

Notes

Request

{
  "finalize": true,
  "rows":[
    {"Customer code": "ABC123", "Customer name": "ABC Customer"},
    {"Customer code": "DEF456", "Customer name": "DEF Customer"}
  ]
}

Replace all rows in the lookup with the rows in the request.

Requires user authentication.
finalize - optional. True if no more rows will be added and the updated lookup should be sent to devices.
rows - optional. The field names must match the names specified in columns when the lookup was created.
If the existing lookup contains a large number of rows, or if a large number of rows is included in the request body, the request may fail.
fileName - optional. The name of a file previously uploaded at POST /files/{fileName}.
fileKey - optional. The key of a file previously uploaded at POST /files/{fileName}. If fileName or fileKey is specified, rows will be ignored. The file must be either CSV or xlsx format and the columns in the file must match the columns specified in this request.
fileHasHeaders - optional. Set to false if the file to import does not have a header row.

200 OK

{
  "code": 200,
  "count": 2
}

count - The number of rows added to the lookup in this request.

400

Bad Request

{
  "code": 951,
  "message": "Time out error. Please try a smaller request."
}

Error code 951 indicates that there are too many existing rows in the lookup to remove in one request, or the number of rows in this request is too large to process in one request. Empty the lookup by calling DELETE /lookups/{key}/rows until complete = true, and then add the rows by calling POST /lookups/{key}/rows.

DELETE /lookups/{key}

Response

Notes

200 OK

Delete a lookup.

Requires user authentication.
Form based lookups can not be deleted.
Lookups that are currently used by forms can not be deleted. Ensure that no forms are using this lookup by checking GET /lookups/{key}/forms.
Lookups that contain rows can not be deleted. Empty the lookup by calling DELETE /lookups/{key}/rows.

GET /lookups/{key}/columns

Response

Notes

[
  {
    "name": "Part_Number",
    "caption": "Part number"
  },
  {
    "name": "Part_Name",
    "caption": "Part name"
  }
]

Return the columns in a lookup.

Requires user authentication.

GET /lookups/{key}/forms

Response

Notes

[
  {
    "key": "fgh123",
    "id": "acme$$12345$$Published",
    "name": "First Form v1",
    "displayName": "First Form",
    "createTime": "2019-08-20T16:55:20.130Z",
    "createUser": "me@me.com",
    "updateTime": "2019-08-20T17:55:21.799Z",
    "updateUser": "me@me.com",
    "version": 1.01
  }
]

Return the forms that currently use the lookup.

Requires user authentication.

GET /lookups/{key}/rows

Response

Notes

[
  {
    "Customer code": "ABC123", 
    "Customer name": "ABC Customer",
    "@id": 6496995632218112
  },
  {
    "Customer code": "DEF456", 
    "Customer name": "DEF Customer",
    "@id": 4667408283598848
  }
]

Return the rows in a lookup.

Requires user authentication.
Data for form based lookups should be retrieved at GET /submissions.
Use @skip and @limit query parameters to page through rows.
Query for specific records by specifying a single column value in the query string.
@id - The unique identifier assigned to each row in the lookup. Use this value to update individual rows at PUT /lookups/{key}/rows/{id}.
Example queries:
- /lookups/lmn123/rows?Customer code=ABC123
- /lookups/lmn123/rows?@skip=100&@limit=100

POST /lookups/{key}/rows

Body

Notes

Request

[
  {
    "Customer code": "GHI789", 
    "Customer name": "GHI Customer"
  },
  {
    "Customer code": "JKL012", 
    "Customer name": "JKL Customer"
  }
]

Append rows to a lookup.

Requires user authentication.
Use query parameter @finalize=true to mark the lookup as ready to distribute to devices.

200 OK

{
  "code": 200,
  "count": 2
}

count - The number of records added to the lookup in this request.

DELETE /lookups/{key}/rows

Response

Notes

{
  "code": 200,
  "complete": true
}

Delete rows from a lookup.

Requires user authentication.
complete - true if all records have been removed from the lookup. Call the endpoint repeatedly until complete = true before beginning any other operation on the lookup.

GET /lookups/{key}/rows/{id}

Response

Notes

{
  "Customer code": "DEF456", 
  "Customer name": "DEF Customer",
  "@id": 4667408283598848
}

Get a single row in a lookup by id.

Requires user authentication.

PUT /lookups/{key}/rows/{id}

Body

Notes

Request

{
  "Customer code": "DEF456", 
  "Customer name": "DEF Customer New Name"
}

Update a row in a lookup.

Requires user authentication.
Use query parameter @finalize=true to mark the lookup as ready to distribute to devices.

200 OK

{
  "Customer code": "DEF456", 
  "Customer name": "DEF Customer New Name",
  "@id": 4667408283598848
}

DELETE /lookups/{key}/rows/{id}

Response

Notes

200 OK

Remove a row from a lookup.

Requires user authentication.
Use query parameter @finalize=true to mark the lookup as ready to distribute to devices.

GET /notifications/{key}

Response

Notes

{
  "key": "nop123",
  "submissionKey": "abc123",
  "webserviceId": "acme$$12345$$Published$$67890",
  "customerKey": "cde123",
  "event": "create",
  "status": "completed",
  "message": "One record updated."
}

Returns the requested webhook notification.

Requires user or webservice authentication.
See Webhooks for more information.

PUT /notifications/{key}

Body	Notes
{ "status": "completed", "message": "One record updated." }	Requires user or webservice authentication. status can be one of "completed", "failed". message (optional) is any message for the end user. Maximum 1,000 characters. See Webhooks for more information.

GET /projects

Response

Notes

[
  {
    "key": "pqr123",
    "name": "Main Project"
  },
  {
    "key": "pqr234",
    "name": "Second Project"
  }
]

Returns all projects the user or web service has access to.

Requires user or webservice authentication.

GET /projects/{key}

Response

Notes

{
  "key": "pqr123",
  "name": "Main Project"
}

Returns the requested project.

Requires user or webservice authentication.

GET /projects/{key}/activity?

Response

Notes

[
  {
    "key": "act124",
    "submissionKey": "abc123",
    "projectKey": "pqr123",
    "formKey": "fgh123",
    "receiveTime": "2019-08-20T15:35:19.139-04:00",
    "type": "update",
    "submissionId": "acme$$12345$$Published&&1",
    "submissionName": "My name | 3",
    "projectName": "Main Project",
    "formName": "First Form v1",
    "userId": "me@me.com",
    "userName": "My Name"
  },
  {
    "key": "act123",
    "submissionKey": "abc123",
    "projectKey": "pqr123",
    "formKey": "fgh123",
    "receiveTime": "2019-08-20T14:38:54.896-04:00",
    "type": "new",
    "submissionId": "acme$$12345$$Published&&1",
    "submissionName": "My name | 3",
    "projectName": "Main Project",
    "formName": "First Form v1",
    "userId": "5551231234",
    "userName": "Device one"
  }
]

Returns all submission activity for a project that the user has access to.

Requires user or webservice authentication.
Required query parameters:
- @beginTime - ISO formatted date/time inclusive
- @endDate - ISO formatted date/time exclusive
Requires user token authentication.
To query all activity, see the /activity? endpoint.

GET /projects/{key}/forms?

Response

Notes

[
  {
    "key": "fgh123",
    "id": "acme$$12345$$Published",
    "name": "First Form v1",
    "displayName": "First Form",
    "createTime": "2019-08-20T16:55:20.130Z",
    "createUser": "me@me.com",
    "updateTime": "2019-08-20T17:55:21.799Z",
    "updateUser": "me@me.com",
    "version": 1.01
  },
  {
    "key": "fgh234",
    "id": "acme$$23456$$Published",
    "name": "Second Form",
    "displayName": "Second Form",
    "createTime": "2019-07-20T16:55:20.130Z",
    "createUser": "me@me.com",
    "updateTime": "2019-07-20T17:55:21.799Z",
    "updateUser": "me@me.com",
    "version": 1.0
  }
]

Returns all forms assigned to the requested project.

Requires user or webservice authentication.
See the /forms endpoint for more detail.
Set optional query parameter @abandoned=true to include forms that have data for the project but are not assigned to the project. Ignored if the authenticated user does not have rights to view abandoned data.

GET /reports

Response

Notes

[
  {
    "key": "rst123",
    "name": "Report 1"
  },
  {
    "key": "rst124",
    "name": "Report 2"
  },
  {
    "key": "rst125",
    "name": "Report 3"
  }
]

Returns all published reports.

Requires user authentication.
Requires report manager rights.

GET /reports/my

Response

Notes

[
  {
    "key": "rst123",
    "name": "Report 1"
  },
  {
    "key": "rst124",
    "name": "Report 2"
  }
]

Returns reports assigned to the user.

Requires user authentication.

GET /reports/{key}

Response

Notes

{
  "key": "rst123",
  "name": "Report 1"
}

Returns the requested report.

Requires user authentication.

GET /reports/{key}/results

Response

Notes

[
  {
    "key": "qrs123",
    "createDate": "2020-03-20T16:30:15.517Z",
    "type": "pdf",
    "name": "Report-1.pdf"
  },
  {
    "key": "qrs124",
    "createDate": "2020-03-23T16:33:16.022Z",
    "type": "pdf",
    "name": "Report-1.pdf"
  }
]

Returns all current results for the selected report.

Requires user authentication.
Report results are purged after seven days.
Possible values for type:
- pdf
- xlsx

GET /reports/{key}/results/{result key}

Response

Notes

{
  "key": "qrs123",
  "createDate": "2020-03-20T16:30:15.517Z",
  "type": "pdf",
  "name": "Report-1.pdf"
}

Returns the details for the selected result.

Requires user authentication.

GET /reports/{key}/results/{result key}/pdf

Response

Notes

Content-Type: application/pdf
Content-Disposition: filename="Report-1.pdf"

Returns the PDF file for the selected result.

Requires user authentication.
Only valid for results with type=pdf

GET /reports/{key}/results/{result key}/xlsx

Response

Notes

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="Report-1.xlsx"

Returns the Excel file for the selected result.

Requires user authentication.
Only valid for results with type=xlsx

GET /submissions?

Response

Notes

[
  {
    "key": "abc123",
    "id": "acme$$12345$$Published&&1"
  },
  {
    "key": "abc124",
    "id": "acme$$12345$$Published&&2"
  }
]

Returns submission identifiers that match a query.

Requires user or webservice authentication.
The project and form to query must be specified in one of two ways:
- By using web service authentication.
- Or by specifying @projectKey and @formKey in the URL.
The following system fields can be queried:
- @receiveTime - The date and time the submission was first received by the doForms servers.
- @statusTime - The date and time the status was last changed.
- @updateTime - The date and time the submission was last edited.
- @status - The current status of the submission.
Any user defined field that is not inside a table or repeatable can be queried by using the data name of the field as the parameter name.
Include a parameter once for an equals condition:
- A single parameter for date and date/time fields is interpreted as requesting a 24 hour range beginning with the parameter value.
- A single parameter for time fields is interpreted as requesting a 1 minute range beginning with the parameter value.
Include a parameter twice for a between condition:
- The first value is inclusive (greater than or equal) and the second is exclusive (less than).
The first field specified in the parameters is used as the primary condition:
- Text comparison is case sensitive.
- Text sorting is UTF-8 (e.g. "Z" is before "a").
- Optimize query performance by using the condition that will return the fewest records as the primary condition.
- To use case insensitive text comparison, provide a date range parameter as the primary condition.
Date/time parameters:
- Use ISO date/time format with timezone offset.
- If the offset is positive, URL encode the plus as %2B.
- The date portion is ignored when querying time type fields.
- The time portion is ignored when querying date type fields.
URL encode text parameter values.
Numeric parameters:
- Use a period to specify decimal place.
Use @limit and @skip to specify a range of records to return.
- If @limit is not specified a default value of 200 is used.
- If @skip is not specified a default value of 0 is used.
- If the number of submissions returned matches @limit, then more submissions remain to be retrieved.
Example queries:
- Get submissions by received date range for a 24 hour period. Project and form specified by web service authentication:
  - /submissions?@receiveTime=2019-09-15T13:08:36.000-04:00&@receiveTime=2019-09-16T13:08:36.000-04:00
- Get submissions where Order_Code = "A123". Project and form specified as URL parameters:
  - /submissions?@projectKey=pqr123&@formKey=fgh123&Order_Code=A123

DELETE /submissions/{key or id}

Response

Notes

200 OK

Delete a submission

Requires user or webservice authentication.
Any related dispatch record can be deleted at /dispatches/{key or id}.

GET /submissions/{key or id}?

Response

Notes

{ "key": "abc123",
  "id": "acme$$12345$$Published&&1",
  "name": "My name | 3",
  "type": "submission",
  "dispatchKey": "abc456",
  "formKey": "fgh123",
  "formName": "First Form v1",
  "formVersion": 1.0,  
  "offset": -240,
  "ownerId": "5551231234",
  "ownerName": "Device one",
  "ownerType": "device",
  "projectKey": "pqr123",
  "openTime": "2019-08-20T14:20:19.378-04:00",
  "createTime": "2019-08-20T14:38:51.591-04:00",
  "receiveTime": "2019-08-20T14:38:54.896-04:00",
  "sourceId": "me@me.com",
  "sourceName": "My Name",
  "sourceType": "user",
  "status": "Completed",
  "statusTime": "2019-08-20T15:30:24.052-04:00",
  "timezone": "Eastern Daylight Time",
  "updateTime": "2019-08-20T15:35:19.139-04:00",
  "updateUser": "me@me.com",  
  "fields": [
    { "name": "Name",
      "data": "text",
      "type": "text",
      "text": "My name" 
    },
    { "name": "Choose",
      "data": "text",
      "type": "choose_one",
      "text": "3"
    },
    { "name": "Form_Title",
      "data": "text",
      "type": "label",
      "text": "Form_Title"
    },
    { "name": "Signature",
      "data": "blob",
      "type": "signature",
      "blob": { 
        "key": "bcd123",
        "id": "acme$$08202019165520$$Published&&1$$S1",
        "type": "jpg" }
    },
    { "name": "Picture",
      "data": "blob",
      "type": "image",
      "blob": { 
        "key": "bcd124",
        "id": "acme$$08202019165520$$Published&&1$$P1",
        "type": "jpg" }
    },
    { "name": "Today_s_date",
      "data": "date",
      "type": "date_time",
      "date": "2019-08-19T00:00:00.000Z"
    },
    { "name": "Number",
      "data": "integer",
      "type": "numeric",
      "integer": 25
    },
    { "name": "Customer_Table",
      "data": "rows",
      "type": "table",
      "rows": [
        { "index": 0,
          "fields": [
            { "name": "Customer_ID",
              "data": "text",
              "type": "lookup",
              "text": "32-151"
            },
            { "name": "Customer_name",
              "data": "text",
              "type": "text",
              "text": "ABC Companies"
            } ]
        },
        { "index": 1,
          "fields": [
            { "name": "Customer_name",
              "data": "text",
              "type": "text",
              "text": "Global Industries"
            },
            { "name": "Customer_ID",
              "data": "text",
              "type": "lookup",
              "text": "44-158"
            } ]
        } ]
    }
}

Returns the data captured in a form submission by key or id.

Requires user or webservice authentication.
key - The key identifier of the submission.
id - The human readable identifier of the submission.
name - The record name of the submission.
type - The type of data record. Always "submission".
dispatchKey - The key of the dispatch linked to this submission. Populated only if dispatch was used to capture the data. Retrieve the dispatch at /dispatches/{key or id}.
formKey - The key of the form definition.
formName - The name of the form.
formVersion - The form version used to generate this response. May be different than the version used to capture the data.
offset - The number of minutes offset from UTC as captured by the device.
ownerId - The human readable identifier of the record owner. Owner fields are only populated if the record was dispatched or forwarded and represent the last owner of the record.
ownerName - The name of the owner.
ownerType - The owner type. Possible values are "device", "email", "link".
projectKey - The key of the project.
openTime - The time the submission was started on the device in the device local time.
createTime - The time the submission was first saved as complete on the device in the device local time.
receiveTime - The time the submission was received at the server in the device local time.
sourceId - The human readable identifier of the record source. Source fields represent the originator of the record.
sourceName - The name of the source.
sourceType - The source type. Possible values are "device", "link", "user".
deviceId - The device hardware id.
deviceKey - The key of the device.
status - The current status of the record.
statusTime - The time the status was last updated.
timezone - The name of the timezone as captured by the device.
updateTime - The time the submission was last edited.
updateUser - The user name of the last user to edit the submission.
fields - The array of fields. See the /forms/{key} endpoint for more details.
- name - The data name of the field.
- type - The type of control.
- data - The data type. Also indicates the property where the data can be retrieved.
Possible values for data:
- blob - An attachment:
  - key - The key of the attachment.
  - id - The human readable identifier of the attachment.
  - type - The extension that should be used when saving the attachment.
- date - A date value with time set to 00:00 utc.
- datetime - A date/time value in device local time.
- email - An email message:
  - addresses - An array of email addresses.
  - message - The message.
- fax - A fax message:
  - addresses - An array of fax numbers.
  - message - The message on the fax cover page.
- fields - An array of fields.
- integer - An integer value.
- location - A location:
  - longitude - The longitude in decimal format.
  - latitude - The latitude in decimal format.
  - altitude - The altitude in meters.
  - accuracy - The accuracy in meters.
- number - A decimal value.
- rows - An array of rows:
  - index - The row number (zero based).
  - fields - An array of fields.
- strings - An array of strings.
- text - A string.
- time - A time value in device local time with date set to Jan 1, 1970.
Additional form definition information can be returned with each field:
- choices - Add "?choices=true" to the URL to include the list of choices with each choose type field.
- options - Add "?options=true" to the URL to include the additional field options with each field.
- To add both choices and options use: /submissions/{key}?choices=true&options=true
- Including these options may increase the response size substantially.

GET /submissions/{key or id}/activity

Response

Notes

[
  {
    "key": "act123",
    "submissionKey": "abc123",
    "projectKey": "pqr123",
    "formKey": "fgh123",
    "receiveTime": "2019-08-20T18:38:54.896Z",
    "type": "new",
    "submissionId": "acme$$12345$$Published&&1",
    "submissionName": "My name | 3",
    "projectName": "Main Project",
    "formName": "First Form v1",
    "userId": "5551231234",
    "userName": "App User"
  },
  {
    "key": "act124",
    "submissionKey": "abc123",
    "projectKey": "pqr123",
    "formKey": "fgh123",
    "receiveTime": "2019-08-20T19:13:04.387Z",
    "type": "update",
    "submissionId": "acme$$12345$$Published&&1",
    "submissionName": "My name | 3",
    "projectName": "Main Project",
    "formName": "First Form v1",
    "userId": "me@me.com",
    "userName": "My Name"
  }
]

Returns the activity of the selected submission.

Requires user or webservice authentication.
receiveDate - The date the activity occured.
type - new or update.
formName - The record name as calculated at the time of the activity.
userId - The mobile number or email address of the mobile user or web user that made the change.
userName - The nickname or the full name of the mobile user or web user that made the change.

GET /submissions/{key or id}/blobs

Response

Notes

[
  {
    "key": "bcd123",
    "id": "acme$$08202019165520$$Published&&1$$S1",
    "index": 0,
    "field": {...},
    "fileName": "1.jpg",
    "type": "jpg"
  },
  {
    "key": "bcd124",
    "id": "acme$$08202019165520$$Published&&1$$P1",
    "field": {...},
    "fileName": 2.jpg",    
    "type": "jpg"
  }
]

Returns information about all attachment blobs in the form submission by the key or id of the submission.

Requires user or webservice authentication.

DELETE /submissions/{key or id}/blobs

Notes

Delete all attachment blobs from the submission.

Requires user or webservice authentication.

GET /submissions/{key or id}/blobs/{key or id}

Response

Notes

{
  "key": "bcd123",
  "id": "acme$$08202019165520$$Published&&1$$S1",
  "index": 0,
  "field": {...},
  "fileName": "1.jpg",
  "type": "jpg"
}

Returns information about a single blob in a submission.

Requires user or webservice authentication.
index - If the image is in a table or repeatable, the row number of the table or repeatable that contains the image.
field - The field. See /submissions/{key or id} for more information on fields.
fileName - The file name. Is unique within the submission.
type - The file extension.

DELETE /submissions/{key or id}/blobs/{key or id}

Notes

Delete the specified attachment blob.

Requires user or webservice authentication.

GET /submissions/{key or id}/blobs/{key or id}/binary

Response

Notes

application/octet-stream

Returns the binary data of a single blob in a submission.

Requires user or webservice authentication.
Save the binary to a file using the value of the "type" field as the extension.

POST /submissions

Body

Notes

Request

{
  "fields": [
    { "name": "Name",
      "text": "My name" 
    },
    { "name": "Choose",
      "text": "3"
    },
    { "name": "Today_s_date",
      "date": "2019-08-19T00:00:00.000Z"
    },
    { "name": "Number",
      "integer": 25
    },
    { "name": "Customer_Table",
      "rows": [
        { "fields": [
          { "name": "Customer_ID",
            "text": "32-151"
          },
          { "name": "Customer_name",
            "text": "ABC Companies"
          } ]
        },
        { "fields": [
          { "name": "Customer_name",
            "text": "Global Industries"
          },
          { "name": "Customer_ID",
            "text": "44-158"
          } ]
      } ]
  }
}

Add a new submission.

Requires web service authentication.

200 OK

Returns the complete submission after it is added.

PUT /submissions/{key or id}

Body

Notes

Request

{
  "fields": [
    { "name": "Name",
      "text": "My name" 
    },
    { "name": "Choose",
      "text": "3"
    },
    { "name": "Today_s_date",
      "date": "2019-08-19T00:00:00.000Z"
    },
    { "name": "Number",
      "integer": 25
    },
    { "name": "Customer_Table",
      "rows": [
        { "fields": [
          { "name": "Customer_ID",
            "text": "32-151"
          },
          { "name": "Customer_name",
            "text": "ABC Companies"
        } ]
      },
      { "fields": [
        { "name": "Customer_name",
          "text": "Global Industries"
        },
        { "name": "Customer_ID",
          "text": "44-158"
      } ]
    } ]
  }
}

Update an existing submission.

Accepts sparse data. If a field is not included, it will not be updated.
Only the name and value of each field is required.
Requires webservice authentication.

200 OK

Returns the complete submission after the update has been applied.

POST /tasks

Body

Notes

Request

{
  "type":"pdf",
  "templateKey":"tuv123",
  "submissionKey":"stu123"
}

Start a task.

Requires user or webservice authentication.
type - The task type.
- pdf - Convert the submission specified in submissionKey to a PDF file. Contact support@doforms.com to enable PDF generation.
templateKey - (optional) The template to use when generating a PDF file. Get the template key at /templates.
submissionKey - The submission to convert to a PDF file.

200 OK

{
  "key": "vwz123",
  "type": "pdf",
  "complete": false,
  "createTime": "2023-12-13T19:27:57.350Z"
}

Returns the task with the current status.

Most tasks will have complete=false when created. Check the status at GET /tasks/{key}.

GET /tasks/{key}

Response

Notes

{
  "key": "vwz123",
  "type": "pdf",
  "complete": true,
  "createTime": "2023-12-13T19:27:57.350Z",

  "blob": {
    "key": "bcd123",
    "name": "MyFileName",
    "type": "pdf"
  }
}

Get a task.

Requires user or webservice authentication.
type - The task type.
- pdf - The task will convert a submission to a PDF file.
complete - True if the task has completed.
blob - Populated if the task results in a file and the task is complete.
- name - The name of the file.
- type - The file type. Use as the extension when saving the file.

GET /tasks/{key}/xlsx

Response

Notes

Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Content-Disposition: attachment; filename="MyFileName.xlsx"

Get the content of an XLSX file generated by a task.

Requires user or webservice authentication.

GET /tasks/{key}/pdf

Response

Notes

Content-Type: application/pdf
Content-Disposition: filename="MyFileName.pdf"

Get the content of a PDF file generated by a task.

Requires user or webservice authentication.

GET /teams

Response

Notes

[
  {
    "key": "main",
    "name": "Main"
  },
  {
    "key": "tuv123",
    "name": "First Team"
  }
]

Returns all device teams (also known as groups) the user has access to.

Requires user authentication.
Every account includes a team where the key is "main".

GET /teams/{key}

Response	Notes
{ "key": "tuv123", "name": "First Team" }	Returns the requested team.

GET /teams/{key}/devices?

Response

Notes

[
  {
    "key": "def123",
    "name": "Device one",
    "number": "5551231234",
    "teamKey": "tuv123"
  },
  {
    "key": "def234",
    "name": "Device two",
    "number": "5551234321",
    "teamKey": "tuv123"
  }
]

Returns all the devices assigned to the requested team.

Requires user authentication.
Unassigned devices are included in the "main" team.
Optional query parameters: latitude, longitude
- If a device has a lastTrack node, return the distance to the provided latitude and longitude in lastTrack.distanceToTarget.

GET /templates

Response

Notes

[
  {
    "key": "t123",
    "name": "First Excel Template",
    "description": "",
    "active": true,
    "createTime": "2023-07-25T18:12:50.769Z",
    "updateTime": "2023-07-25T18:12:50.769Z"
  },
  {
    "key": "t124",
    "name": "Second Excel Template",
    "description": "",
    "active": true,
    "createTime": "2023-07-25T18:12:50.187Z",
    "updateTime": "2023-07-25T18:12:50.187Z"
  }
]

Returns all Excel templates in the account.

Requires user authentication.

GET /templates/{key}

Response

Notes

{
  "key": "t123",
  "name": "First Excel Template",
  "description": "",
  "active": true,
  "createTime": "2023-07-25T18:12:50.769Z",
  "updateTime": "2023-07-25T18:12:50.769Z"
}

Returns the requested Excel template.

Requires user authentication.

POST /tokens/reseller

Authorization header is not required.

	Body	Notes
Request	{ "username":"me@me.com", "password":"mypassword", "account":"myreseller" }	Use the username, password and account code of a valid doForms reseller account.
200 OK	{ "code": 200 "resellerCode": "myreseller", "resellerKey": "rst123", "token": "tqrstu..." }	Use the token to authorize additional API requests. Token expires after 24 hours. Token provides access to the following endpoints: /customers /devices /forms /groups /projects /teams /users For every request authorized by this token, add the customer code to the URL: ?customerCode={customerCode} Example: /api/v2/devices?customerCode=mycustomer Customer code is not required for requests to /customers.
401 Unauthorized	{ "code": 401 "message": "Bad username, password or account.", }

POST /tokens/user

Authorization header is not required.

	Body	Notes
Request	{ "username":"me@me.com", "password":"mypassword", "account":"myaccount", "code":"123456", "canRefresh": true }	Use the username and password of a valid doForms web user. The account parameter is only required if the user exists in more than one doForms account. The code parameter is only required if a Multi Factor Authentication code has been requested. Set canRefresh to true to include a single use refresh token in the response (optional).
Request	{ "refreshToken": "tuvwxy..." }	Send a refresh token to exchange it for a new authorization token. A new single use refresh token will also be included in the response.
200 OK	{ "code": 200, "customerCode": "myaccount", "customerKey": "cde123", "userKey": "uvw123", "token": "tqrstu...", "refreshToken": "tuvwxy..." }	Use the token to authorize additional API requests. Token expires after 24 hours. customerCode and customerKey are the identifiers of the customer account the authenticated user belongs to. userKey is the identifier of the authenticated user. refreshToken is a single use refresh token that can be exchanged for a new authentication token.
300 Options	{ "code": 300, "accounts": ["myaccount","myaccount2"] }	If no account is specified and the user is valid for more than one doForms account, a list of valid accounts is returned. Add the correct "account" value to the original request body and post again to receive a token.
401 Unauthorized	{ "code": 401, "message": "Bad username, password or account." }
401 MFA Code Required	{ "code": 968, "message": "Validation code required." }	A Multi Factor Authentication code will be sent to the user. Post the same username, password, account (optional), and the code parameter to receive a token.
403 Forbidden	{ "code": 403 "message": "Account does not have API access.", }
403 Inactive Account	{ "code": 990 "message": "Account is not active.", }

POST /tokens/webservice

Authorization header is not required

	Body	Notes
Request	{ "webservice":"acme$$12345$$Published$$67890", "password":"mypassword" }	Use the webservice ID and password of a valid web service.
200 OK	{ "code": 200 "customerCode": "acme", "customerKey": "cde123", "token": "abc123...", }	Use the token to authorize additional API requests. Tokens expire after 24 hours. Token can only be used to access the project and form for the authorized web service.
401 Unauthorized	{ "code": 401 "message": "Bad web service or password.", }
403 Forbidden	{ "code": 403 "message": "Account does not have web service access.", }
403 Inactive Account	{ "code": 990 "message": "Account is not active.", }

GET /users

Response

Notes

[
  {
    "key": "uvw123",
    "email": "me@me.com",
    "firstName": "My",
    "lastName": "Name",
    "workPhone": "(555) 123-1234"
  },
  {
    "key": "uvw124",
    "email": "you@you.com",
    "firstName": "Your",
    "lastName": "Name",
    "groupKey": "ghi123",
    "workPhone": "555 123 1235"
  }
]

Returns all web users for the account.

Requires user authentication.
See /groups/{key}/users for a more limited list of users.

GET /users/{key or email}

Response

Notes

{
  "key": "uvw123",
  "email": "me@me.com",
  "firstName": "My",
  "lastName": "Name",
  "workPhone": "(555) 123-1234"
}

Returns the requested web user by key or by email.

Requires user authentication.

GET /webservices

Response

Notes

[
  {
    "key": "wxy123",
    "id": "acme$$12345$$Published$$67890",
    "active": true,
    "formKey": "fgh123",
    "projectKey": "pqr123"
  },
  {
    "key": "wxy234",
    "id": acme$$23456$$Published$$78901",
    "active": true,
    "formKey": "fgh234",
    "projectKey": "pqr123"
  }
]

Returns all web services for the account.

Requires user authentication.
Authenticated user must have System Manage rights.

GET /webservices/{key or id}

Response

Notes

{
  "key": "wxy123",
  "id": "acme$$12345$$Published$$67890",
  "active": true,
  "formKey": "fgh123",
  "projectKey": "pqr123",
  "password": "mypassword"
}

Returns the requested web service including the password.

Requires user authentication.
Authenticated user must have System Manage rights.

doForms REST Web Service API

URL

Sample Code

Authorization

User token

Web service token

Web service

Reseller token

Endpoints

GET /accounts?

GET /accounts/current

GET /accounts/{key or code}

PUT /accounts/{key or code}

GET /activity?

GET /devices?

GET /devices/{key or number}

GET /devices/{key or number}/activity?

POST /dispatches

GET /dispatches?

DELETE /dispatches/{key or id}

GET /dispatches/{key or id}?

POST /files/{file name}

GET /file/{key or file name}

DELETE /file/{key or file name}

GET /forms

GET /forms/{key or id}

GET /forms/{key or id}/activity?

GET /forms/{key or id}/fields

GET /forms/{key or id}/latest

GET /forms/{key or id}/projects

GET /groups

GET /groups/{key}

GET /groups/{key}/users

GET /lookups

POST /lookups

GET /lookups/{key}

PUT /lookups/{key}

DELETE /lookups/{key}

GET /lookups/{key}/columns

GET /lookups/{key}/forms

GET /lookups/{key}/rows

POST /lookups/{key}/rows

DELETE /lookups/{key}/rows

GET /lookups/{key}/rows/{id}

PUT /lookups/{key}/rows/{id}

DELETE /lookups/{key}/rows/{id}

GET /notifications/{key}

PUT /notifications/{key}

GET /projects

GET /projects/{key}

GET /projects/{key}/activity?

GET /projects/{key}/forms?

GET /reports

GET /reports/my

GET /reports/{key}

GET /reports/{key}/results

GET /reports/{key}/results/{result key}

GET /reports/{key}/results/{result key}/pdf

GET /reports/{key}/results/{result key}/xlsx

GET /submissions?

DELETE /submissions/{key or id}

GET /submissions/{key or id}?

GET /submissions/{key or id}/activity

GET /submissions/{key or id}/blobs

DELETE /submissions/{key or id}/blobs

GET /submissions/{key or id}/blobs/{key or id}

DELETE /submissions/{key or id}/blobs/{key or id}

GET /submissions/{key or id}/blobs/{key or id}/binary

POST /submissions

PUT /submissions/{key or id}

POST /tasks

GET /tasks/{key}

GET /tasks/{key}/xlsx

GET /tasks/{key}/pdf

GET /teams

GET /teams/{key}

GET /teams/{key}/devices?

GET /templates

GET /templates/{key}

POST /tokens/reseller