Documents API

Documents API

Field Squared supports a RESTful API that handles both single object and list operations.

Documents in Field Squared are written to the API as either a single document or a list of document objects. For most integrations we recommend doing batch updates of documents (create, update) as array operations.

For additional rules around API data types and data handling, please see the API Usage Notes article. All requests to our API must be authenticated with our authentication service. Please read our article on Authenticated HTTP headers and the correct HTTP methods.

Document Object Payload

A document has the following structure by default. We'll explore the makeup of a document throughout this article.

{
   "Name": "My Document",
   "ExternalId": "2302",
   "Type": "INVOICE",
   "OwnerId" : "6789",
   "OwnerClass" : "Task",
   "Lat":39.749911,
   "Lon":-105.000026,
   "LastUpdated": "2017-02-02T21:16:46Z",
   "Created": "2017-01-27T19:09:48Z",
   "Date" : "2017-01-20T20:00:00Z",
   "PercentComplete" : 70,
   "PercentTotal" : 10,
   "PercentDone" : 7,
   "Data": {
      "CDT6": "2017-02-16T22:41:21Z",
      "SMT4": "John Smith"
     }
 }

Working with Single Documents

For single document updates, Field Squared supports the HTTP methods GET, POST and DELETE.

Methods Supported: GET|POST|DELETE
URL: https://api.fieldsquared.com/workspace/api/document/externalid

Where workspace is the unique company ID issued to your company and External Id is the ID of the record in your existing system. Callers to this API must be authenticated and use the X-Auth-Token in the HTTP headers or the request will be rejected by the Field Squared firewall.

Example 1
GET https://api.fieldsquared.com/10/api/document/1234
will retrieve the document 1234 from workspace 10. The structure of the Document returned will look like the payload above.

Example 2:
POST https://api.fieldsquared.com/10/api/document/4567
Creates or updates the document 4567 for workspace 10. Note that all required fields for the document must be populated for the create to be successful. The Document object sent to us should look like the payload above.

Example 3:
DELETE https://api.fieldsquared.com/10/api/document/4567
Removes document 4567 from workspace 10. The document is not deleted permanently and is moved to the archived objects collection and can be restored from the recycle bin.

Working with Lists of Documents

For list/array operations (eg. bulk read and write), Field Squared supports GET and POST operations. DELETE is not supported for list operations.

Methods Supported: GET|POST
URL: https://api.fieldsquared.com/workspace/api/document

Where workspace is the ID we assign to your company.

We support the following query parameters for GET operations:

  • modifiedsince – returns all records modified/edited/created within the Field Squared platform since a given date and time. Dates are an ISO-8901 format date string in UTC time.
  • mintime – returns all records with a 'Date' value >= mintime.  Dates are an ISO-8901 format date string in UTC time.
  • maxtime – returns all records with a 'Date' value <= maxtime.  Dates are an ISO-8901 format date string in UTC time.
  • types – To filter on document type, use the query parameter types and pass a comma separated list of types.
  • ownerid, ownerclass – Returns all documents owned by another object, for example ownerid=ABCD1234&ownerclass=Task

Each Document Type is extensible with custom controls (see below), therefore the API generation tool in App Builder should be used to create the exact API payload that is required for each document type.

The payload for a list of documents is simply an array of document objects like the example below.

[
  {
    "Name": "My Document",
    "ExternalId": "1234",
    "Type": "INVOICE",
    "Data": {}
  },
  {
    "Name": "My Second Document",
    "ExternalId": "1235",
    "Type": "INVOICE",
    "Data": {}
  }
]

Field Squared supports batch updates of multiple documents, or sending through just a single document object in a request within a list. When updating or retrieving a list of documents through our API, you must specify a single document type. It is not possible to bulk update documents of different types, since each document type has its own schema.

Example 1
GET https://api.fieldsquared.com/10/api/document
This retrieves an array of document objects (see below) through the API. Query parameters for this API are supported to add filters to the request.

Example 2
POST https://api.fieldsquared.com/10/api/document
This example can bulk create or update documents of type Boat where each item in the request will be created/updated in the Field Squared database.

Setting up the Message Body

See corresponding section under 'Task API'.  The Document Object Type works identically.

Updating Records using the ExternalID

See corresponding section under 'Task API'.  The Document Object Type works identically.

Document API Properties

Core Properties

The core properties of a document are:

  • Name (required) – the name of the document
  • ExternalId (optional) – the unique ID of the record in your system. If omitted all items in the API request will result in a new record being created.
  • Document Type (required) – the type of this document (eg. "INVOICE" or "INSPECTION"). This must map onto one of the Document Types that have been configured in App Builder for your company.
  • OwnerId (required) – the external ID of the owning object.  This owning object needs to exist Field Squared before the document is posted.
  • OwnerClass (required)- the type of owning object – 'Task', 'Asset', 'Contact' or 'User'.
  • Lat (optional) – Latitude component of document location.
  • Lon (optional) – Longitude component of document location.
  • PercentComplete (optional) – A percentage calculated by comparing the number of controls with values populated to the total number of controls in the document.
  • PercentTotal (optional) – Total number of controls in the document.
  • PercentDone (optional) – Number of controls with values populated in the document.
  • Date (optional) – Date Time value used for 'Time Series' documents that indicates where this document fits within the series.

Minimum JSON body to create a single document

[
 {
   "Name": "Test Document",
   "ExternalId": "1234",
   "Type": "INVOICE",
   }
]

Minimum XML Document body to create a single document

<ArrayOfDocument>
  <Document>
    <Name>Test Document</Name>
    <ExternalId>1234</ExternalId>
    <Type>INVOICE</Type>
  </Document>
</ArrayOfDocument>

Omitting Properties

See corresponding section under 'Task API'.  The Document Object Type works identically.

Setting Document Control Values through the API

Field Squared App Builder allows you to quickly design documents for capturing data in the field by visually dragging controls into a document template canvas and customizing each control.  At a minimum, each control has:

  • A customizable user interface
  • A unique BINDING key to identify the control
  • A label to display on the screen for the control

The Data property on the API is used to set document control values in API integrations.

  • Each message body can send any values you like to the Field Squared API.
  • All values are key-value pairs where the keys are strings and the values are objects.
  • All binding keys must be uppercase.
  • If the keys sent to our API are not configured on that Document Type, then they will be ignored by our API. We only update keys that exist for that document type.
  • To determine the required API structure for the 'Data' field based on the controls included in the document type, click on the 'Workspace'->'Schemas' tab under 'App Builder' and click the 'JSON','XML, 'CSV' or 'CSV Import' button next to the document type to generate the schema.

For example, say we want to update an 'INSPECTION' document type, which has controls with binding keys 'INSPECTION_DATE' and 'INSPECTION_TYPE'. You would update this record using the following sample API calls:

JSON: Data is a dictionary of key-value pairs

 {
   
   "Name": "My Inspection Document",
   "OwnerId" : "6789",
   "OwnerClass" : "Task",
   "ExternalId": "1234",
   "Type": "INSPECTION",
   "Data": {
      "INSPECTION_DATE": "2017-09-02",
      "INSPECTION_TYPE": "Regular"
   }
  }

Sub Documents

One of the controls that can be added when building a document template is a Details Table.  This provides a table of data that links to sub-documents that contain their own large amounts of data.  When you have complex tabular data that you want to see in a single view, but you want data entry to be easy for field workers, the Details table is a good solution.  The screenshot below shows an invoice document that uses a sub-document to store data related to each line item:

All document control values, including sub-document values, are represented within the 'Data' field of the document as structured JSON.  The sub-document above, using a binding DTBL1, will show as follows when querying the document through the API:

   "Data": {
      "DTBL1": [
         {
            "RATE": "120.0",
            "TOTAL": 360,
            "CT8": {
               "UNITPRICE": "120.0",
               "NAME": "Consulting",
               "ID": "12"
            },
            "DESC": "System Design",
            "SMT3": "3"
         },
         {
            "RATE": "65",
            "TOTAL": 455,
            "CT8": {
               "UNITPRICE": "0.0",
               "NAME": "Travel",
               "ID": "14"
            },
            "DESC": "",
            "SMT3": "7"
         },
         {},
         {},
         {}
      ],
   }

By structuring the JSON request in this way, you can also POST a document that includes sub-document data.

Document Address Properties

See corresponding section under 'Task API'.  The Document Object Type works identically.

Diff Updates using the Last Updated Field

See corresponding section under 'Task API'.  The Document Object Type works identically.

Was this article helpful?

Yes No

Related Articles