Click or drag to resize
GET /forms
Print this page
Description

This service can be used to search forms based on a combination of filters.

The filters in a query are joined together as AND, so only forms that meet all the filter conditions are returned.

If form_ids, job_ids, driver_ids or unit_ids were specified in the conditions, all forms from different drivers will be included in the search. Otherwise, the query will be limited for the forms created by the current driver.

Tip Tip

When filtering forms by time, a narrower timeframe can be used to improve the performance of your query.

Examples of a valid requests:

Copy
GET /forms?from=2013-03-01T06:00:00Z
        &to=2013-03-15T20:00:00Z
        &template_ids=eb8fab4eae8b4634932f5c0e71e11463
        &unit_ids=12345,23456,34567
        &history=HeadersOnly
Copy
GET /forms?from=2013-03-01T06:00:00Z
        &to=2013-03-15T20:00:00Z
        &$filter=fields/any(f:f/name eq 'Phone number' and f/value eq '555-555-555')
        &$orderby=address
        &return_fields=true
Request

No request body is used for this service.

Optional parameters

NameValueDescription
fromISO 8601 timestampLimit the query to forms created after the given timestamp.
toISO 8601 timestampLimit the query to forms created before the given timestamp.
limitintMaximum number of form objects to return.
current_version_numberstringVersion number value as used on the form object.
form_typestringForm type value as used on the form and template objects.
template_idsstringList of alphanumeric template identifiers, separated by commas.
form_idsstringList of alphanumeric form identifiers, separated by commas.
job_idsstringList of alphanumeric job identifiers, separated by commas.
driver_idsstringList of driver identifiers in integer form, separated by commas.
unit_idsstringList of unit identifiers in integer form, separated by commas.
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

Available oData query commands

NameValueDescription
$filterstring Standard OData filtering operation. For details see the 4.5. Filter System Query Option ($filter) section of the OData URI Conventions documentation
$orderbystring Standard OData ordering operation. For details see the 4.2. Orderby System Query Option ($orderby) section of the OData URI Conventions documentation
$topstring Number of objects to return. For details see the 4.3. Top System Query Option ($top) section of the OData URI Conventions documentation
$skipstring Number of objects to exclude from the top of the results. For details see the 4.4. Skip System Query Option ($skip) section of the OData URI Conventions documentation
Response

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

Member Type Purpose
id 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.