Click or drag to resize
GET /forms?job_id=<job_id>
Print this page
Description

This service is used to retrieve all of the form instances that are associated with a specific job.

The requested forms are identified by the Job_Id value that is added to the end of the URL.

Example of a valid request:

Copy
GET /forms?job_id=eb8fab4eae8b4634932f5c0e71e11463
Request

No request body is used for this service.

Optional parameters

NameValueDescription
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
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.