doForms
API docs by Redocly

doForms REST API (2.0.1)

Download OpenAPI specification:Download

URL: https://www.doforms.com/contact-us/

doForms REST API documentation

REST API guide

Java sample code

C# sample code

/accounts

Query customer accounts and return a list of accounts.

Authorizations:
ResellerTokenAuthentication
query Parameters
administrator.email
string

Query for accounts that have this email address as the administrator.

code
string

Query for accounts that have this account code.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/accounts/current

Get information about the current account.

Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
{
  • "key": "ATDcLZjKmcO5dSqP6ga9s0l7XVsslk",
  • "code": "acmeinc",
  • "administrator": {
    },
  • "billingCountry": "US",
  • "billingState": "NJ",
  • "currency": "USD",
  • "branded": true,
  • "credits": 10,
  • "expires": "2023-03-16T15:56:50.341Z",
  • "licenses": 1,
  • "name": "Acme Inc Corp Ltd Pty",
  • "packageCode": "package01",
  • "plan": {
    },
  • "resellerCode": "abc001",
  • "status": "Paid",
  • "active": true
}

/accounts/current

Update the status of the current account.

Authorizations:
UserTokenAuthentication
Request Body schema: application/json
required

New activity status for current account.

active
required
boolean

Set to true to activate the account, false to deactivate the account.

Responses

Request samples

Content type
application/json
{
  • "active": true
}

Response samples

Content type
application/json
{
  • "key": "ATDcLZjKmcO5dSqP6ga9s0l7XVsslk",
  • "code": "acmeinc",
  • "administrator": {
    },
  • "billingCountry": "US",
  • "billingState": "NJ",
  • "currency": "USD",
  • "branded": true,
  • "credits": 10,
  • "expires": "2023-03-16T15:56:50.341Z",
  • "licenses": 1,
  • "name": "Acme Inc Corp Ltd Pty",
  • "packageCode": "package01",
  • "plan": {
    },
  • "resellerCode": "abc001",
  • "status": "Paid",
  • "active": true
}

/accounts/{keyOrCode}

Get a single customer account by key or code.

  • Returns an account with the corresponding key.
Authorizations:
ResellerTokenAuthentication
path Parameters
keyOrCode
required
string
Examples:
  • ATDcLZjKmcO5dSqP6ga9s0l7XVsslk - key
  • acmeinc - code

An account's identifying key or code.

Responses

Response samples

Content type
application/json
{
  • "key": "ATDcLZjKmcO5dSqP6ga9s0l7XVsslk",
  • "code": "acmeinc",
  • "administrator": {
    },
  • "billingCountry": "US",
  • "billingState": "NJ",
  • "currency": "USD",
  • "branded": true,
  • "credits": 10,
  • "expires": "2023-03-16T15:56:50.341Z",
  • "licenses": 1,
  • "name": "Acme Inc Corp Ltd Pty",
  • "packageCode": "package01",
  • "plan": {
    },
  • "resellerCode": "abc001",
  • "status": "Paid",
  • "active": true
}

/accounts/{keyOrCode}

Update the status of the specified account.

Authorizations:
ResellerTokenAuthentication
path Parameters
keyOrCode
required
string
Examples:
  • ATDcLZjKmcO5dSqP6ga9s0l7XVsslk - key
  • acmeinc - code

An account's identifying key or code.

Request Body schema: application/json
required

New activity status for given account.

active
required
boolean

Set to true to activate the account, false to deactivate the account.

Responses

Request samples

Content type
application/json
{
  • "active": true
}

Response samples

Content type
application/json
{
  • "key": "ATDcLZjKmcO5dSqP6ga9s0l7XVsslk",
  • "code": "acmeinc",
  • "administrator": {
    },
  • "billingCountry": "US",
  • "billingState": "NJ",
  • "currency": "USD",
  • "branded": true,
  • "credits": 10,
  • "expires": "2023-03-16T15:56:50.341Z",
  • "licenses": 1,
  • "name": "Acme Inc Corp Ltd Pty",
  • "packageCode": "package01",
  • "plan": {
    },
  • "resellerCode": "abc001",
  • "status": "Paid",
  • "active": true
}

/activity

Returns all submission activity the user has access to.

  • 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?
Authorizations:
UserTokenAuthentication
query Parameters
beginTime
required
string <date>

ISO formatted date/time inclusive for activity date range.

endTime
required
string <date>

ISO formatted date/time exclusive for activity date range.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/appointments

Returns all appointments (scheduled dispatches) the user has access to, limited by query parameters.

  • Required query parameters:
    • date - ISO formatted date (e.g. 2024-04-19)
    • range - Size of date range: day, week, month
  • Optional query parameters:
    • deviceKey - Limit appointments to the specified device
    • email - Limit appointments to the specified email address
  • Example requests:
    • Get all appointments for a single day:
      • /appointments?date=2024-04-19&range=day
    • Get all appointments for a device for April:
      • /appointments?date=2024-04-19&range=month&deviceKey=def123
Authorizations:
UserTokenAuthentication
query Parameters
date
required
string <date>

ISO formatted date to query (e.g. 2024-04-19).

range
required
string
Enum: "day" "week" "month"

Size of date range to query.

email
string

Query for appointments assigned to this email.

deviceKey
string

Query for appointments assigned to this device.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/appointments/{key}

Returns an apointment by key.

  • See POST /dispatches to add a new appointment.
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "date": "2024-06-15",
  • "time": "13:25",
  • "sequence": 9,
  • "duration": 60,
  • "key": "NvOnO7W4st3ijb1DKeCucmNcPQhxLZ",
  • "year": 2024,
  • "month": 6,
  • "week": 24,
  • "day": 15,
  • "createTime": "2024-06-13T17:23:37.000Z",
  • "createUser": "me@me.com",
  • "dispatch": {
    }
}

/appointments/{key}

Update an existing appointment.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Request Body schema: application/json
required

The updated appointment.

date
string <date>

The date of the appointment.

time
string

The time of the appointment in local time

sequence
integer <int64>

If the appointment is not scheduled for a specific time, the sequence to sort the appointment

duration
integer <int64>

The duration of the appointment in minutes

Responses

Request samples

Content type
application/json
{
  • "date": "2024-06-15",
  • "time": "13:25",
  • "sequence": 9,
  • "duration": 60
}

Response samples

Content type
application/json
{
  • "date": "2024-06-15",
  • "time": "13:25",
  • "sequence": 9,
  • "duration": 60,
  • "key": "NvOnO7W4st3ijb1DKeCucmNcPQhxLZ",
  • "year": 2024,
  • "month": 6,
  • "week": 24,
  • "day": 15,
  • "createTime": "2024-06-13T17:23:37.000Z",
  • "createUser": "me@me.com",
  • "dispatch": {
    }
}

/devices

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.
  • With optional query parameters: latitude, longitude
    • If a device has a lastTrack node, return the distance to the provided latitude and longitude in lastTrack.distanceToTarget.
Authorizations:
UserTokenAuthentication
query Parameters
latitude
number <double>

Positional latitude to compare with device's latitude.

longitude
number <double>

Positional longitude to compare with device's longitude.

skip
integer <int32>

Skips the specified number of items.

  • If not specified a default value of 0 is used.
limit
integer <int32>

Limits how many items will be returned.

  • If not specified a default value of 1000 is used.
  • If limit is greater than 1000 an error will be returned.
  • If the number of items returned matches limit, then more items remain to be retrieved.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/devices/{keyOrNumber}

Get the requested device by key or number.

  • If number = "Available" the device license has not been assigned to a device.
  • With optional query parameters: latitude, longitude
    • If a device has a lastTrack node, return the distance to the provided latitude and longitude in lastTrack.distanceToTarget.
Authorizations:
UserTokenAuthentication
path Parameters
keyOrNumber
required
string
Examples:
  • PeXiYqsrKwM4PS7fQQbh6kCDlgL0ip - key
  • 5551231234 - number

A device's identifying key or number.

query Parameters
latitude
number <double>

Positional latitude to compare with device's latitude.

longitude
number <double>

Positional longitude to compare with device's longitude.

Responses

Response samples

Content type
application/json
{
  • "key": "PeXiYqsrKwM4PS7fQQbh6kCDlgL0ip",
  • "number": "5551231234",
  • "name": "Device one",
  • "email": "me@me.com",
  • "carrier": "string",
  • "createTime": "2021-03-22T15:33:29.382Z",
  • "formTime": "2024-07-18T17:15:57.355Z",
  • "model": "iPhone13,4",
  • "os": "iOS 17.4.1",
  • "teamKey": "R4Tk0BDrc8z8P5xGcF3sgIOs1c243C",
  • "geotabDeviceId": "string",
  • "geotabDeviceName": "string",
  • "updateTime": "2023-03-16T15:56:50.341Z",
  • "version": "8.7.4",
  • "lastTrack": {
    },
  • "variable1": "string",
  • "variable2": "string",
  • "variable3": "string",
  • "variable4": "string",
  • "variable5": "string",
  • "variable6": "string",
  • "variable7": "string",
  • "variable8": "string",
  • "variable9": "string",
  • "variable10": "string"
}

/devices/{keyOrNumber}/activity

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

  • To query all activity, see the /activity? endpoint.
Authorizations:
UserTokenAuthentication
path Parameters
keyOrNumber
required
string
Examples:
  • PeXiYqsrKwM4PS7fQQbh6kCDlgL0ip - key
  • 5551231234 - number

A device's identifying key or number.

query Parameters
beginTime
required
string <date>

ISO formatted date/time inclusive for activity date range.

endTime
required
string <date>

ISO formatted date/time exclusive for activity date range.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/dispatches

Returns dispatch identifiers that match a query.

  • 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.
  • 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.
  • Example queries:
    • Get dispatches by received date range for a 24 hour period. Project and form specified by web service authentication:
      • /dispatches?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:
      • /dispatches?projectKey=pqr123&formKey=fgh123&Order_Code=A123
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
query Parameters
projectKey
string

The project's identification key.

formKey
string

The form's identification key.

receiveTime
string <date>

The date and time the item was first received by the doForms servers.

statusTime
string <date>

The date and time the status was last changed.

updateTime
string <date>

The date and time the item was last edited.

status
string

The current status of the item.

limit
integer <int32>

Limits how many items will be returned.

  • If not specified a default value of 1000 is used.
  • If limit is greater than 1000 an error will be returned.
  • If the number of items returned matches limit, then more items remain to be retrieved.
skip
integer <int32>

Skips the specified number of items.

  • If not specified a default value of 0 is used.
userDefinedField
any

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/dispatches

Add a new dispatch.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
Request Body schema: application/json
required

The new dispatch to add.

formKey
string

The key of the form definition.

projectKey
string

The key of the project.

ownerId
string

The mobile number of the device to receive the dispatch. If no device is assigned, the dispatch will be set to Pending status. Set either the ownerId or the ownerKey to send the dispatch.

ownerKey
string

The key of the device to receive the dispatch. If no device is assigned, the dispatch will be set to Pending status.

object

The appointment for the dispatch.

required
Array of objects (SubmissionMinimalField)

An array of fields to populate. All fields are optional

  • Only the "name" and one value property ("text", "integer", "date", etc.) are required for each field.
appointmentDateTime
string
appointmentDurationHrs
string

Responses

Request samples

Content type
application/json
{
  • "formKey": "xcK9i7mROHAf0YqfasbSvY17ayaT72",
  • "projectKey": "tKR3OgfdLuzUDkipbQuhT1OH7h001E",
  • "ownerId": "5551231234",
  • "ownerKey": "PTDcLZjKccO5dSnP6ga9s0l7XVsslk",
  • "appointment": {
    },
  • "fields": [
    ],
  • "appointmentDateTime": "string",
  • "appointmentDurationHrs": "string"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "key": "kuQaqlVcCKwr8QbNUYFZcDT1HkNHue",
  • "ownerKey": "J48KPeKMu67IgnUt7wmoedbIQV4U8d",
  • "message": "string",
  • "status": "Sent"
}

/dispatches/{keyOrId}

Returns a dispatch record by key or id.

  • See /submissions/{key} endpoint for more details.
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

query Parameters
choices
boolean

Set to true to include the list of choices with each choose type field.

options
boolean

Set to true to include the additional field options with each field.

signUrls
integer

Set to an integer to provide signed URLs for downloading blobs. URLs expire after this number of minutes.

Responses

Response samples

Content type
application/json
{
  • "formKey": "xcK9i7mROHAf0YqfasbSvY17ayaT72",
  • "projectKey": "tKR3OgfdLuzUDkipbQuhT1OH7h001E",
  • "key": "yROnO7W4st2ijb1DJeCucmNcPQhxLZ",
  • "id": "acmeinc$$12345$$Published&&1",
  • "name": "My name | 3",
  • "formName": "First Form v1",
  • "ownerId": "5551231234",
  • "ownerName": "Device one",
  • "ownerType": "device",
  • "projectName": "Main Project",
  • "deviceKey": "ATDcLZjKmcO5dSqP6ga9s0l7XVsslk",
  • "statusTime": "2019-08-20T15:30:24.052-04:00",
  • "systemStatus": "Viewed",
  • "appointment": {
    },
  • "index": 1,
  • "type": "dispatch",
  • "formVersion": 1,
  • "openTime": "2019-08-20T14:25:19.139-04:00",
  • "createTime": "2019-08-20T14:32:19.139-04:00",
  • "receiveTime": "2019-08-20T14:38:54.896-04:00",
  • "sourceId": "me@me.com",
  • "sourceName": "My Name",
  • "sourceType": "user",
  • "submissionKey": "vXOnO9W4st2ijb1DJeCucmNcPQhxLZ",
  • "status": "On site",
  • "updateTime": "2019-08-20T15:35:19.139-04:00",
  • "updateUser": "me@me.com",
  • "deleteTime": "2019-08-24T15:35:19.139Z",
  • "deleteUser": "me@me.com",
  • "timezone": "Eastern Daylight Time",
  • "offset": -240,
  • "fields": [
    ]
}

/dispatches/{keyOrId}

Delete a dispatch.

  • Any related submission can be deleted at /submissions/{key or id}.
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/activity

Returns all feed activity the user has access to.

  • To query feed activity by device, form or project, see the these endpoints:
    • GET /devices/{key or number}/feed?
    • GET /forms/{key or id}/feed?
    • GET /projects/{key}/feed?
Authorizations:
UserTokenAuthentication
query Parameters
beginTime
required
string <date>

ISO formatted date/time inclusive for activity date range.

endTime
required
string <date>

ISO formatted date/time exclusive for activity date range.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/files/{filename}

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

  • Accepts csv and xlsx type files.
  • If the same file name is used again, the existing file will be overwritten.
  • Files are automatically deleted after 30 days.
  • Files larger than 32MB will return a 413 error.
  • Use TWO STEPS To upload a large file:
    • FIRST, leave the body empty on this request. Three new properties will be returned: putUrl, contentType, contentDisposition.
    • SECOND, send a PUT request to the putUrl with the file content in the body, using the contentType and contentDisposition as headers.
Authorizations:
UserTokenAuthentication
path Parameters
filename
required
string
Example: My lookup.csv

The file's name, INCLUDING the extension.

Request Body schema: application/octet-stream
required

File binary data to upload.

string <binary>

Responses

Response samples

Content type
application/json
{
  • "key": "FQVgW96RHRxVApCH3bLlHlXL1q1RXS",
  • "name": "My lookup.csv",
  • "size": 2276338,
  • "md5": "08/CmK5m0xPyyPJxf8X+vA==",
  • "createTime": "2019-07-18T19:22:40.958Z",
  • "updateTime": "2019-07-18T19:52:38.600Z",
  • "expireTime": "2019-08-17T19:52:38.600Z",
  • "contentType": "text/csv",
  • "contentDisposition": "filename=\"My lookup.csv\"",
  • "putUrl": "https://storage.googleapis.com/..."
}

/files/{keyOrName}

Get information about a file.

Authorizations:
UserTokenAuthentication
path Parameters
keyOrName
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • My lookup.csv - name

An file's identifying key or file name (including extension).

Responses

Response samples

Content type
application/json
{
  • "key": "FQVgW96RHRxVApCH3bLlHlXL1q1RXS",
  • "name": "My lookup.csv",
  • "size": 2276338,
  • "md5": "08/CmK5m0xPyyPJxf8X+vA==",
  • "createTime": "2019-07-18T19:22:40.958Z",
  • "updateTime": "2019-07-18T19:52:38.600Z",
  • "expireTime": "2019-08-17T19:52:38.600Z"
}

/files/{keyOrName}

Delete a file.

  • Files are automatically deleted after 30 days.
Authorizations:
UserTokenAuthentication
path Parameters
keyOrName
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • My lookup.csv - name

An file's identifying key or file name (including extension).

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/forms

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

  • Does not include the form fields. Retrieve the full form definition at /forms/{keyOrIdOrName}.
  • If the account contains a large number of forms, the /projects/{key}/forms endpoint is recommended.
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/forms/{keyOrIdOrName}

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

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrIdOrName
required
string
Examples:
  • omEfRaCSsWQMXsOr9sXWkcbbS6WGPX - key
  • acmeinc$$12345$$Published - id
  • First Form v1 - name

A form's identifying key, id or name.

Responses

Response samples

Content type
application/json
{
  • "key": "omEfRaCSsWQMXsOr9sXWkcbbS6WGPX",
  • "name": "First Form v1",
  • "id": "acmeinc$$12345$$Published",
  • "displayName": "First Form v1",
  • "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": [
    ],
  • "dateFormat": { }
}

/forms/{keyOrIdOrName}/activity

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

  • To query all activity, see the /activity? endpoint.
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrIdOrName
required
string
Examples:
  • omEfRaCSsWQMXsOr9sXWkcbbS6WGPX - key
  • acmeinc$$12345$$Published - id
  • First Form v1 - name

A form's identifying key, id or name.

query Parameters
beginTime
required
string <date>

ISO formatted date/time inclusive for activity date range.

endTime
required
string <date>

ISO formatted date/time exclusive for activity date range.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

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

Returns the submission in a simplified format that uses the data name of the question as the JSON property name./n- See the customer specific API documentation for a version of this endpoint that defines the response format for each form definition.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrIdOrIndex
required
string
Examples:
  • VzJ8lRqvNf5Rk4CGG2hPhJPN709gFv - key
  • acmeinc$$12345$$Published&&1 - id
  • 1 - index

A data record's identifying key, id or index.

keyOrIdOrName
required
string
Examples:
  • omEfRaCSsWQMXsOr9sXWkcbbS6WGPX - key
  • acmeinc$$12345$$Published - id
  • First Form v1 - name

A form's identifying key, id or name.

query Parameters
signUrls
integer

Set to an integer to provide signed URLs for downloading blobs. URLs expire after this number of minutes.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/forms/{keyOrIdOrName}/fields

Returns the list of fields for a form.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrIdOrName
required
string
Examples:
  • omEfRaCSsWQMXsOr9sXWkcbbS6WGPX - key
  • acmeinc$$12345$$Published - id
  • First Form v1 - name

A form's identifying key, id or name.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/forms/{keyOrIdOrName}/latest

Returns information about the last submission generated for the form.

  • Use to identify the range of submissions that can be retrieved at /submissions/{keyOrId}.
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrIdOrName
required
string
Examples:
  • omEfRaCSsWQMXsOr9sXWkcbbS6WGPX - key
  • acmeinc$$12345$$Published - id
  • First Form v1 - name

A form's identifying key, id or name.

Responses

Response samples

Content type
application/json
{
  • "id": "acmeinc$$12345$$Published&&1",
  • "index": 1
}

/forms/{keyOrIdOrName}/projects

Get all the projects the user has access to that the specified form is assigned to.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrIdOrName
required
string
Examples:
  • omEfRaCSsWQMXsOr9sXWkcbbS6WGPX - key
  • acmeinc$$12345$$Published - id
  • First Form v1 - name

A form's identifying key, id or name.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/forms/{keyOrIdOrName}/submissions/{keyOrIdOrIndex}

Returns the submission in a standard format.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrIdOrIndex
required
string
Examples:
  • VzJ8lRqvNf5Rk4CGG2hPhJPN709gFv - key
  • acmeinc$$12345$$Published&&1 - id
  • 1 - index

A data record's identifying key, id or index.

keyOrIdOrName
required
string
Examples:
  • omEfRaCSsWQMXsOr9sXWkcbbS6WGPX - key
  • acmeinc$$12345$$Published - id
  • First Form v1 - name

A form's identifying key, id or name.

query Parameters
signUrls
integer

Set to an integer to provide signed URLs for downloading blobs. URLs expire after this number of minutes.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/groups

Returns all groups in the account.

  • Web users can be assigned to a group.
Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/groups/{key}

Returns the requested group by key.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "pTLiPMvpsVpBfIB7KtoijCVX0VN7CS",
  • "name": "Group One"
}

/groups/{key}/users

Returns all users assigned to the requested group.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/api/v2/integrations/100/quotes

Request Body schema: application/json
string

Responses

Request samples

Content type
application/json
"string"

/lookups

Returns all lookups in the account.

Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/lookups

Add a new lookup.

  • NOTE: Form based lookups can not be added via the API.
Authorizations:
UserTokenAuthentication
Request Body schema: application/json
required

New lookup data.

name
required
string

If the name provided duplicates the name of an existing lookup, the name will be made unique.

description
string
finalize
boolean

True if all rows are included in this request. The lookup will be marked as ready to deliver to devices.

encrypt
boolean

True if the lookup should be encrypted at rest.

  • NOTE: The account must have field encryption enabled to use encryption.
required
Array of objects

The columns in the lookup. Columns can not be changed after the lookup is created.

rows
Array of any

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
string

The name of a file previously uploaded at POST /files/{fileName}.

fileKey
string

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
boolean

Set to false if the file to import does not have a header row.

Responses

Request samples

Content type
application/json
{
  • "name": "Customer_List",
  • "description": "List of customers",
  • "finalize": true,
  • "encrypt": false,
  • "columns": [
    ],
  • "rows": [
    ],
  • "fileName": "My lookup.csv",
  • "fileKey": "fil123",
  • "fileHasHeaders": false
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "string",
  • "count": 2,
  • "complete": true,
  • "httpResponseCode": 0,
  • "isSuccess": true,
  • "Lookup": {
    }
}

/lookups/{key}

Return a lookup.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "7A8QKyQxuhAuzuTq4qWSJUrurUyw2c",
  • "name": "Lookups_Parts_Form",
  • "description": "Displaying different lookup attributes",
  • "useForm": true,
  • "useFilter": false,
  • "formKey": "uGUKhCN5cSBZyv9sJL3bQ37M1eY2OP",
  • "projectKey": "7UrvTnPY91unSCSOek7QNPFkjB4g1l",
  • "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": [
    ]
}

/lookups/{key}

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

  • 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.
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Request Body schema: application/json
string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "string",
  • "count": 2,
  • "complete": true,
  • "httpResponseCode": 0,
  • "isSuccess": true
}

/lookups/{key}

Delete a lookup.

  • 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.
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/lookups/{key}/columns

Return the columns in a lookup.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/lookups/{key}/forms

Return the forms that currently use the lookup.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/lookups/{key}/rows

Return the rows in a lookup.

  • Data for form based lookups should be retrieved at GET /submissions.
  • 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
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

query Parameters
skip
integer <int32>

Skips the specified number of items.

  • If not specified a default value of 0 is used.
limit
integer <int32>

Limits how many items will be returned.

  • If not specified a default value of 1000 is used.
  • If limit is greater than 1000 an error will be returned.
  • If the number of items returned matches limit, then more items remain to be retrieved.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/lookups/{key}/rows

Append rows to a lookup.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

query Parameters
finalize
boolean

Set to true to mark a lookup as ready to distribute to devices.

Request Body schema: application/json
string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "string",
  • "count": 2,
  • "complete": true,
  • "httpResponseCode": 0,
  • "isSuccess": true
}

/lookups/{key}/rows

Delete rows from a lookup.

  • 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
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "code": 200,
  • "message": "string",
  • "count": 2,
  • "complete": true,
  • "httpResponseCode": 0,
  • "isSuccess": true,
  • "Lookup": {
    }
}

/lookups/{key}/rows/{rowId}

Get a single row in a lookup by id.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

rowId
required
string
Example: 4667408283598848

A row's id.

Responses

Response samples

Content type
application/json
{
  • "Customer code": "DEF456",
  • "Customer name": "DEF Customer",
  • "@id": 4667408283598848
}

/lookups/{key}/rows/{rowId}

Update a row in a lookup.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

rowId
required
string
Example: 4667408283598848

A row's id.

query Parameters
finalize
boolean

Set to true to mark a lookup as ready to distribute to devices.

Request Body schema: application/json
string

Responses

Request samples

Content type
application/json
"string"

Response samples

Content type
application/json
{
  • "Customer code": "DEF456",
  • "Customer name": "DEF Customer New Name",
  • "@id": 4667408283598848
}

/lookups/{key}/rows/{rowId}

Remove a row from a lookup.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

rowId
required
string
Example: 4667408283598848

A row's id.

query Parameters
finalize
boolean

Set to true to mark a lookup as ready to distribute to devices.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/notifications

Returns webhook notifications that match the query.

  • See Webhooks for more information.
  • Add the cursor parameter to additional requests if more = true.
Authorizations:
WebserviceTokenAuthentication
query Parameters
limit
integer <int32>

Limits how many items will be returned.

  • If not specified a default value of 1000 is used.
  • If limit is greater than 1000 an error will be returned.
  • If the number of items returned matches limit, then more items remain to be retrieved.
status
required
string
Enum: "new" "retry" "rejected" "received" "completed" "failed"

The status of webhook notifications to query.

cursor
string

The current cursor location for additional query requests.

beginDate
string <date>

Begin date exclusive.

endDate
string <date>

End date inclusive.

Responses

Response samples

Content type
application/json
{
  • "notifications": [
    ],
  • "cursor": "string",
  • "more": true
}

/notifications/{key}

Returns the requested webhook notification.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "FbprQyAcCLLa945awbQST6iegmXbB2",
  • "customerKey": "WhLnDFSuhjh1xtfM7xK5x7icbPePxt",
  • "dispatchKey": "G8lfW9FSuhjh1xtfM7xK5x7icbPePxt",
  • "submissionKey": "t1hwi8R7EBh0w2dSwmC0YZzZ3JO1Yg",
  • "webserviceId": "acmeinc$$12345$$Published$$67890",
  • "event": "create",
  • "status": "completed",
  • "message": "One record updated.",
  • "url": "string",
  • "dispatchStatus": "string",
  • "createTime": "2019-08-17T19:52:38.600Z",
  • "updateTime": "2019-08-17T19:52:38.600Z",
  • "dispatch": {
    },
  • "submission": {
    }
}

/notifications/{key}

Returns the requested webhook notification.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Request Body schema: application/json
required

Updated notification result.

status
required
string
Enum: "received" "completed" "failed"

status can be one of "completed", or "failed".

message
string

Any message for the end user. Maximum 1,000 characters.

eventStatus
object

Responses

Request samples

Content type
application/json
{
  • "status": "completed",
  • "message": "One record updated.",
  • "eventStatus": { }
}

Response samples

Content type
application/json
{
  • "key": "FbprQyAcCLLa945awbQST6iegmXbB2",
  • "customerKey": "WhLnDFSuhjh1xtfM7xK5x7icbPePxt",
  • "dispatchKey": "G8lfW9FSuhjh1xtfM7xK5x7icbPePxt",
  • "submissionKey": "t1hwi8R7EBh0w2dSwmC0YZzZ3JO1Yg",
  • "webserviceId": "acmeinc$$12345$$Published$$67890",
  • "event": "create",
  • "status": "completed",
  • "message": "One record updated.",
  • "url": "string",
  • "dispatchStatus": "string",
  • "createTime": "2019-08-17T19:52:38.600Z",
  • "updateTime": "2019-08-17T19:52:38.600Z",
  • "dispatch": {
    },
  • "submission": {
    }
}

/projects

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

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/projects/{key}

Returns the requested project.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "1LlrXfUoLnQns0gUa26BO97KaMABah",
  • "name": "Main Project"
}

/projects/{key}/activity

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

  • To query all activity, see the /activity? endpoint.
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

query Parameters
beginTime
required
string <date>

ISO formatted date/time inclusive for activity date range.

endTime
required
string <date>

ISO formatted date/time exclusive for activity date range.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/projects/{key}/forms

Returns all forms assigned to the requested project.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

query Parameters
abandoned
boolean

Set to 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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/reports

Returns all published reports.

  • Requires report manager rights.
Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/reports/my

Returns reports assigned to the user.

Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/reports/{key}

Returns the requested report.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "EN0cAd24sgZehDN78JLgkzkqIUipYV",
  • "name": "Report 1"
}

/reports/{key}/results

Returns all current results for the selected report.

  • Report results are purged after seven days.
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "dBWGHV4pb3GZgdN5hTkxdbP6CjQT42",
  • "createDate": "2020-03-20T16:30:15.517Z",
  • "type": "pdf",
  • "name": "Report-1.pdf"
}

/reports/{key}/results/{resultKey}

Returns the details for the selected result.

  • Report results are purged after seven days.
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

resultKey
required
string
Example: xqBNFSHLkbP1aEZgEDHOwwSdAvh7CH

A result's key.

Responses

Response samples

Content type
application/json
{
  • "key": "dBWGHV4pb3GZgdN5hTkxdbP6CjQT42",
  • "createDate": "2020-03-20T16:30:15.517Z",
  • "type": "pdf",
  • "name": "Report-1.pdf"
}

/reports/{key}/results/{resultKey}/pdf

Returns the PDF file for the selected result.

  • Only valid for results with type=pdf.
  • Report results are purged after seven days.
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

resultKey
required
string
Example: xqBNFSHLkbP1aEZgEDHOwwSdAvh7CH

A result's key.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/reports/{key}/results/{resultKey}/xlsx

Returns the Excel file for the selected result.

  • Only valid for results with type=xlsx.
  • Report results are purged after seven days.
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

resultKey
required
string
Example: xqBNFSHLkbP1aEZgEDHOwwSdAvh7CH

A result's key.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/sections

Returns all sections (also known as data groups) the user has access to.

Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/sections/{key}

Returns the requested section.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "main",
  • "name": "Main"
}

/submissions

Returns submission identifiers that match a query.

  • 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.
  • 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.
  • 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
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
query Parameters
projectKey
string

The project's identification key.

formKey
string

The form's identification key.

receiveTime
string <date>

The date and time the item was first received by the doForms servers.

statusTime
string <date>

The date and time the status was last changed.

updateTime
string <date>

The date and time the item was last edited.

status
string

The current status of the item.

limit
integer <int32>

Limits how many items will be returned.

  • If not specified a default value of 1000 is used.
  • If limit is greater than 1000 an error will be returned.
  • If the number of items returned matches limit, then more items remain to be retrieved.
skip
integer <int32>

Skips the specified number of items.

  • If not specified a default value of 0 is used.
userDefinedField
any

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.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/submissions

Add a new submission.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
Request Body schema: application/json
required

The new submission to add.

ownerId
string

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.

formKey
object

The key of the form definition.

projectKey
string

The key of the project.

Array of objects (SubmissionMinimalField)

An array of fields containing the data of the submission.

  • Only the "name" and one value property ("text", "integer", "date", etc.) are required for each field.

Responses

Request samples

Content type
application/json
{
  • "ownerId": "5551231234",
  • "formKey": "DH1s7l6ylvH06POROchW1pycjaHCdu",
  • "projectKey": "V4oI6jMg31Qqe9jG94orfnYj8gLE2d",
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "key": "nPZr6U2z3Az3qxA987NgFmHsDiiikW",
  • "ownerKey": "fNp5zU2z3Az3qxA987NgFmHsDiiikW",
  • "message": "string",
  • "status": "Completed",
  • "submission": {
    }
}

/submissions/{keyOrId}

Returns a submission record by key or id.

  • Dispatch specific fields: submissionKey, systemStatus
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

query Parameters
choices
boolean

Set to true to include the list of choices with each choose type field.

options
boolean

Set to true to include the additional field options with each field.

signUrls
integer

Set to an integer to provide signed URLs for downloading blobs. URLs expire after this number of minutes.

Responses

Response samples

Content type
application/json
{
  • "ownerId": "5551231234",
  • "formKey": "DH1s7l6ylvH06POROchW1pycjaHCdu",
  • "projectKey": "V4oI6jMg31Qqe9jG94orfnYj8gLE2d",
  • "key": "sQXR6U2z3Az3qxA987NgFmHsDiiikW",
  • "id": "acmeinc$$12345$$Published&&1",
  • "index": 1,
  • "name": "My name | 3",
  • "type": "submission",
  • "dispatchKey": "i7FjKtVSVFJbIIqcHNl0sAdtiILYBR",
  • "formName": "First Form v1",
  • "formVersion": 1,
  • "ownerName": "Device one",
  • "ownerType": "device",
  • "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",
  • "deviceId": "5551231234",
  • "deviceKey": "fZMR6U2z3Az3qxA987NgFmHsDiiikW",
  • "status": "Completed",
  • "statusTime": "2019-08-20T15:30:24.052-04:00",
  • "updateTime": "2019-08-20T15:35:19.139-04:00",
  • "updateUser": "me@me.com",
  • "deleteTime": "2019-08-21T15:35:19.139-04:00",
  • "deleteUser": "me@me.com",
  • "timezone": "Eastern Daylight Time",
  • "offset": -240,
  • "fields": [
    ]
}

/submissions/{keyOrId}

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.
Authorizations:
WebserviceTokenAuthentication
path Parameters
keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

Request Body schema: application/json
required

The updated submission data.

Array of objects (SubmissionMinimalField)

An array of fields containing the data of the submission.

Responses

Request samples

Content type
application/json
{
  • "fields": [
    ]
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "key": "nPZr6U2z3Az3qxA987NgFmHsDiiikW",
  • "ownerKey": "fNp5zU2z3Az3qxA987NgFmHsDiiikW",
  • "message": "string",
  • "status": "Completed",
  • "submission": {
    }
}

/submissions/{keyOrId}

Delete a submission.

  • Any related dispatch record can be deleted at /dispatches/{key or id}.
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/submissions/{keyOrId}/activity

Returns the activity of the selected submission.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/submissions/{keyOrId}/blobs

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

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/submissions/{keyOrId}/blobs

Delete all attachment blobs from the submission.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/submissions/{keyOrId}/blobs/{blobKeyOrId}

Returns information about a single blob in a submission.

  • Get blob content at /submissions/{keyOrId}/blobs/{blobKeyOrId}/binary
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
blobKeyOrId
required
string
Examples:
  • NGf1jN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$08202019165520$$Published&&1$$S1 - id

The blob's identifying key or id.

keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

Responses

Response samples

Content type
application/json
{
  • "key": "ECj636f16SqHglY4B2noIkZRu1TahA",
  • "id": "acmeinc$$08202019165520$$Published&&1$$P1",
  • "index": 1,
  • "field": {
    },
  • "fileName": "1.jpg",
  • "type": "jpg",
  • "signedUrl": { }
}

/submissions/{keyOrId}/blobs/{blobKeyOrId}

Delete the specified attachment blob.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
blobKeyOrId
required
string
Examples:
  • NGf1jN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$08202019165520$$Published&&1$$S1 - id

The blob's identifying key or id.

keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/submissions/{keyOrId}/blobs/{blobKeyOrId}/binary

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

  • Save the binary to a file using the value of the "type" field as the extension.
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
blobKeyOrId
required
string
Examples:
  • NGf1jN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$08202019165520$$Published&&1$$S1 - id

The blob's identifying key or id.

keyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The record's identifying key or id.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/tasks

Start a task.

  • Most tasks will have complete=false when created.
    • Check the status at GET /tasks/{key}.
Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
Request Body schema: application/json
required

The new task to start.

type
required
string
Enum: "pdf" "xlsx"

The task type.

  • Contact support@doforms.com to enable generation.
  • pdf - Convert the submission specified in submissionKey to a PDF file.
  • xlsx - Convert the submission specified in submissionKey to an Excel file.
submissionKey
string

The submission to convert to a PDF or Excel file.

templateKey
string

The template to use when generating a file. Get the template key at /templates.

  • REQUIRED if converting to Excel file.
  • If generating PDF file without a template key then it will default to a standard PDF file.

Responses

Request samples

Content type
application/json
{
  • "type": "pdf",
  • "submissionKey": "DTCIFMpGRGvoUqBnCzOhYcbn8KAqP3",
  • "templateKey": "abP9HdcIxDv5bhFLpPIUl0w9IQmlLH"
}

Response samples

Content type
application/json
{
  • "key": "r1czN7YJGFyzUnVQOr0stFcz81XWzi",
  • "type": "pdf",
  • "complete": true,
  • "createTime": "2023-12-13T19:27:57.350Z",
  • "completeTime": "2023-12-14T23:18:24.120Z",
  • "message": "string",
  • "blob": {
    }
}

/tasks/{key}

Get a task.

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "r1czN7YJGFyzUnVQOr0stFcz81XWzi",
  • "type": "pdf",
  • "complete": true,
  • "createTime": "2023-12-13T19:27:57.350Z",
  • "completeTime": "2023-12-14T23:18:24.120Z",
  • "message": "string",
  • "blob": {
    }
}

/tasks/{key}/pdf

Get the content of a PDF file generated by a task

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/tasks/{key}/xlsx

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

Authorizations:
UserTokenAuthenticationWebserviceTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "code": 400,
  • "request": "Dsl9NhcFgqzDASjb",
  • "exception": "IllegalArgumentException",
  • "message": "Client error example."
}

/teams

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

  • Every account includes a team where the key is "main".
Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

/teams/{key}

Returns the requested team.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "main",
  • "name": "Main"
}

/teams/{key}/devices

Returns all the devices assigned to the requested team.

  • Unassigned devices are included in the "main" team.
  • With optional query parameters: latitude, longitude
    • If a device has a lastTrack node, return the distance to the provided latitude and longitude in lastTrack.distanceToTarget.
Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

query Parameters
latitude
number <double>

Positional latitude to compare with device's latitude.

longitude
number <double>

Positional longitude to compare with device's longitude.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/templates

Returns all Excel templates in the account.

Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/templates/{key}

Returns the requested Excel template.

Authorizations:
UserTokenAuthentication
path Parameters
key
required
string
Example: ARGJZN3aUcuRXYNREmgRP9oYa4Dse9

The object's identifying key.

Responses

Response samples

Content type
application/json
{
  • "key": "LKqSyquTXMVX4pjvb59lwZucJIqqqo",
  • "name": "First Excel Template",
  • "description": "Example template description.",
  • "active": true,
  • "createTime": "2023-07-25T18:12:50.769Z",
  • "updateTime": "2023-07-25T18:12:50.769Z"
}

/tokens/reseller

Request a reseller token.

  • 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.
Authorizations:
None
Request Body schema: application/json
required

The data required to request a reseller token.

username
string

Use the username of a valid doForms reseller account.

password
string

Use the password of a valid doForms reseller account.

account
string

Use the account code of a valid doForms reseller account.

Responses

Request samples

Content type
application/json
{
  • "username": "me@me.com",
  • "password": "mypassword",
  • "account": "myreseller"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "resellerCode": "reseller001",
  • "resellerKey": "Ajjc8HTBBbCrKA2EZFzwpdR8nIkWXY",
  • "token": "1PwN35.C0f1g6xumxOf8KGNJeUiVM2...",
  • "message": "string"
}

/tokens/user

Request a user token.

Authorizations:
None
Request Body schema: application/json
required

The data required to request a user token.

username
string

Use the username of a valid doForms web user.

password
string

Use the password of a valid doForms web user.

account
string

Only required if the user exists in more than one doForms account.

code
string

Only required if a Multi Factor Authentication code has been requested.

canRefresh
boolean

Set to true to include a single use refresh token in the response.

refreshToken
string

Responses

Request samples

Content type
application/json
Example

Request a new token.

{
  • "username": "me@me.com",
  • "password": "mypassword",
  • "account": "myaccount",
  • "code": "123456",
  • "canRefresh": true
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "token": "eyJhbGciOiJIUzI1NiJ9.eyJjdXMiO...",
  • "message": "string",
  • "customerCode": "acmeinc",
  • "customerKey": "YuEiQ2QUTc61MKKb0PDt02WJ3yCQHE",
  • "userKey": "djprtE6DZQMkAGuCty1PZhx2kaKjIt",
  • "accounts": [
    ],
  • "refreshToken": "8mWRVy2IaB7Gg.46yV0Yh25ob1cBH6..."
}

/tokens/webservice

Request a webservice token.

Authorizations:
None
Request Body schema: application/json
required

The data required to request a webservice token.

password
string

Use the password of a valid web service.

webservice
string

Use the webservice ID of a valid web service.

Responses

Request samples

Content type
application/json
{
  • "password": "mypassword",
  • "webservice": "acmeinc$$12345$$Published$$67890"
}

Response samples

Content type
application/json
{
  • "code": 200,
  • "token": "TlUqQ3xRIaQICcgWgd.mPrpbJZQqDJ...",
  • "message": "string",
  • "customerCode": "acmeinc",
  • "customerKey": "YfggYZwnyVQGF3crpNuPv2XQfu7ava"
}

/users

Returns all web users for the account.

  • See /groups/{key}/users for a more limited list of users.
Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/users/{keyOrEmail}

Returns the requested web user by key or by email.

Authorizations:
UserTokenAuthentication
path Parameters
keyOrEmail
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • me@me.com - email

A user's identifying key or email.

Responses

Response samples

Content type
application/json
{
  • "key": "bodamkKDaEf3119xMhutBB7tuDCjno",
  • "email": "me@me.com",
  • "firstName": "My",
  • "lastName": "Name",
  • "groupKey": "string",
  • "dataGroupKey": "string",
  • "projectForm": {
    },
  • "time": {
    },
  • "units": "english",
  • "workPhone": "(555) 123-1234",
  • "rights": {
    }
}

/webservices

Returns all web services for the account.

  • Authenticated user must have System Manage rights.
Authorizations:
UserTokenAuthentication

Responses

Response samples

Content type
application/json
[
  • {
    }
]

/webservices/{webserviceKeyOrId}

Returns the requested web service including the password.

  • Authenticated user must have System Manage rights.
Authorizations:
UserTokenAuthentication
path Parameters
webserviceKeyOrId
required
string
Examples:
  • ARGJZN3aUcuRXYNREmgRP9oYa4Dse9 - key
  • acmeinc$$12345$$Published&&1 - id

The webservices' identifying key or id.

Responses

Response samples

Content type
application/json
{
  • "key": "h0Rbk53PKQTPO8aYKWtshF9deL8mVw",
  • "id": "acmeinc$$12345$$Published$$67890",
  • "active": true,
  • "formKey": "Xloe36wa6u43houLxWEXdhLmrHjzi2",
  • "password": "mypassword",
  • "projectKey": "WUDCQtofDAjAS38SyWOjMxkFGfbOPJ"
}