GET /forms/<id>[,<id>]*

Description

This service is used to retrieve one or more form instances. You can retrieve the details of a single form (such as one previously submitted) or multiple forms.

The requested forms are identified by FormId values that are added to the end of the URL, separated by commas.

Tip
You can get up to 5 Id values at a time this way; to get all of the forms associated with a job, use GET /forms?job_id=<job_id>.

Example of a valid request:

Copy

GET /forms/eb8fab4eae8b4634932f5c0e71e11463,635df5b638ad45d4ac1e631139634003,6e8c2379d81f4ae78b4ddc03ce7ed35d

Request

No request body is used for this service.

Optional parameters

Name	Value	Description
updated_since	ISO 8601 timestamp	Finds items by modification time. This retrieves only those objects with one or more timestamp members, one of which falls after the specified timestamp.
list_all	false (default), true	(only usable with updated_since) If set to true, list_all retrieves a comprehensive list: ProductName returns a larger set of results that includes the IDs (or primary key values) of every object that falls within the selection range and the JSON for the updated objects. Setting list_all to true can be used, for example, if you need to refresh a local cache.
history	string (default: "None")	This option controls how many previously submitted versions will be returned with the form objects. Available options: None: no history, the "previousVersions" property of the form objects will always be null HeadersOnly: history without XML data, the "previousVersions" property of the form objects will contain a list of previously submitted form objects, but without XML data (so all with empty "value" property) to keep the response size small FullContent: history with XML data, the "previousVersions" property of the form objects will contain a list of previously submitted form objects
return_fields	false (default), true	If set to "true", the returned form objects will include the fields property

Response

On success, the response is a JSON array of form objects:

Member

Type

Purpose

string

(required) A GUID that uniquely identifies the form.

versionId

string

(required) A GUID that uniquely identifies the revision of the form.

previousVersionId

string

(required if a previous revision exists) A GUID that uniquely identifies this revision's parent revision.

template

string

(required) A GUID that uniquely identifies the template on which this form is based.

status

string

Indicates the current status of the form. Values: Submitted (default), Saved. This field can be updated through the API. If not specified, this field defaults to Submitted. If Saved, the form can be retrieved for completion and submission.

submissionTime

string

The ISO 8601 timestamp for when this form was changed to Submitted. Read-only once set. If not provided, it is set by the server automatically.

values

string

(required) A string containing an XML document that contains all the values submitted by the user into this form. The structure of this XML document should match the form template: This field can be updated through the API.

job

string

Uniquely identifies the job that is associated with this form. This field is required when creating a new form.

lastUpdateTime

string

(read-only) The most recent timestamp for the form, which is the submitted time, update time, or creation time (in that order).

driverName

string

(read-only) The tag for the driver who is associated with the form.

unitName

string

(read-only) The tag for the driver's unit at the time that the form was last updated.

jobName

string

(read-only) The tag for the job that is associated with the form.

address

string

(read-only) The form's address, which is the driver's location (usually the job site) when last updating the form.

formType

string

(read-only) The form's type, which is given by the template that this form is based on. This is "standard" by default.

readOnly

bool?

(read-only) Indicates whether form cannot be edited.

versionNumber

int?

(read-only) The current version number of the form instance. The version number starts at 1 and increments on the next revision after each submitted revision. Saved revisions share the same version number as their submitted revision.

previousVersions

Form[]

(read-only) The list of previously submitted form objects (the content of this property is controlled by the "history" request parameter).

fields

FormField[]

(read-only) The content of the form as a flat list of the Field objects detailed below (this property is omitted by default, to include use the "return_fields=true" request parameter).

Member	Type	Purpose
id	string	(read-only) Uniquely identifies the field. This is an integer identifier.
name	string	(read-only) Name of the field.
type	string	(read-only) Type of the field.
value	string	(read-only) Value of the field.

templateRevisionNumber

int?

(read-only) The revision number of the template used to create this form.

openTime

string

(read-only) Time when the form was most recently opened by the user for editing.

closeTime

string

(read-only) Time when the form was most recently closed by the user after editing was complete.

openDuration

int

(read-only) The length of time that this form revision was edited for, in seconds

All available fields are included in the response objects.

If the request fails, an Error Response is generated.