Assets API

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

Assets in Field Squared are written to the API as either a single asset or a list of asset objects. For most integrations we recommend doing batch updates of assets (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.

Asset Object Payload

An asset has the following structure by default. We'll explore the makeup of an asset throughout this article.

{
   "Name": "My Speed Boat",
   "ExternalId": "2302",
   "Type": "Boat",
   "Parent": "6789",
   "Lat":39.749911,
   "Lon":-105.000026,
   "StreetAddress": "1514 Blake St",
   "Unit": "Suite 200",
   "City": "Denver",
   "State": "CO",
   "Zip": "80202-1322,
   "LastUpdated": "2017-02-02T21:16:46Z",
   "Created": "2017-01-27T19:09:48Z",
   "Data": {
      "MY_TEXT_FIELD": "Some sample text",
      "MY_NUMBER_FIELD": "1234",
      "MY_TIME_FIELD": "00:30:00",
      "MY_DATE_FIELD": "2017-01-23",
      "MY_DATE_TIME_FIELD": "2017-01-27T19:14:46Z",
      "SAMPLE_BARCODE_SCAN_FIELD": "234234esfs2"
    }
    "Tasks": ["1234ABCD","5678GDFDK"],
    "Team" : "8837BKDS",
 }

Working with Single Assets

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

Methods Supported: GET|POST|DELETE
URL: https://api.fieldsquared.com/workspace/api/asset/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/asset/1234
will retrieve the asset 1234 from workspace 10. The structure of the Asset returned will look like the payload above.

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

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

Working with Lists of Assets

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/asset

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.
• nodeid – To filter and return all assets below asset X in the hierarchy, use the query parameter nodeid = X where X is the externalid of the top level asset.
• root – To filter and return all root level assets, use the query parameter root = true
• assettypes – To filter on asset type, use the query parameter assettypes and pass a comma separated list of types.

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

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

[
  {
    "Name": "My Asset",
    "ExternalId": "1234",
    "Type": "Boat",
  },
  {
    "Name": "My Second Asset",
    "ExternalId": "1235",
    "Type": "Boat",
 }
]

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

Example 1
GET https://api.fieldsquared.com/10/api/asset
This retrieves an array of asset 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/asset
This example can bulk create or update assets 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 Asset Object Type works identically.

Updating Records using the ExternalID

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

Asset API Properties

Core Properties

The core properties of an asset are:

• Name (required) – the name of the asset
• 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.
• Asset Type (required) – the type of this asset (eg. "Boat" or "Truck"). This must map onto one of the Asset Types that have been configured in App Builder for your company.
• Parent (optional) – the external ID of the parent asset.  This parent asset needs to exist Field Squared before the child asset is posted. Populating this parent value allows an N level asset hierarchy to be modeled in Field Squared.
• Tasks (optional) – List of ExternalID's of related Tasks
• Team (optional) – ExternalID of team that the asset is assigned to.  Teams control the visibility of the asset to users of the system.  i.e. An asset may be tagged with a Team that is responsible for a specific geographic region.  Only Field Squared users that are part of that team will see that asset within the Field Squared mobile app.

Minimum JSON body to create a single asset

[
 {
   "Name": "Test Boat Asset for API",
   "ExternalId": "1234",
   "Type": "Boat",
   }
]

Minimum XML Asset body to create a single asset

<ArrayOfAsset>
  <Asset>
    <Name>Test Boat Asset for API</Name>
    <ExternalId>1234</ExternalId>
    <Type>Boat</Type>
  </Asset>
</ArrayOfAsset>

Omitting Properties

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

Setting Custom Fields through the API

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

Asset Address Properties

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

Diff Updates using the Last Updated Field

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