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.
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:
No request body is used for this service.
|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.
|return_fields||false (default), true||If set to "true", the returned form objects will include the fields property|
On success, the response is a JSON array of form objects:
|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).
|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|