Teams API

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

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

Team Object Payload

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

{
        "ExternalId": "7a6a8fa2-b3d0-4c47-aae3-c5ee3de3b6a8",
        "Name": "A Team",
        "Lat":39.749911,
        "Lon":-105.000026,
        "StreetAddress": "1514 Blake St",
        "Unit": "Suite 200",
        "City": "Denver",
        "State": "CO",
        "Zip": "80202-1322",
        "Enabled": true,
        "Data": {
            "TextArea": "HELLO",
            "AUTO_NUM": "VVX74",
            "Number": "1234",
            "TIME": "00:30:00",
            "Date": "2017-01-23",
            "DateTime": "2017-01-27T19:14:46Z",
            "Barcode": "234234esfs"
        },
        "Members": [
            "jTZv6YcMaStulDcIMOrs4AAA4A"
        ],
        "Teams": [
            "098sd0SVoukdklsVidkdSedsk3"
        ], 
        "LastUpdated": "2017-01-30T18:43:22Z",
        "Created": "2017-01-30T18:43:22Z" 
}

Working with Single Teams

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

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

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

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

Working with Lists of Teams

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

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.

The Team Class 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 the Team Class.

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

[
  {
    "Name": "Team A",
    "ExternalId": "1234",
  },
  {
    "Name": "Team B",
    "ExternalId": "1235",
 }
]

Field Squared supports batch updates of multiple teams, or sending through just a single team object in a request within a list.

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

Updating Records using the ExternalID

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

Team API Properties

Core Properties

The core properties of a team are:

• Name (required) – the name of the team
• 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.
• Name (required) – Full name for team.
• Enabled (required) – true/false boolean to indicate if the team is enabled and can login to the app.
• Members (optional) – List of ExternalID's of users that are part of the team.
• Teams (optional) – List of ExternalID's of teams that the team is related to.  The team.teams relationship is used to model Teams that are geographically adjacent to each other.

Minimum JSON body to create a single team

[
 {
   "Name": "Team A",
   "ExternalId": "1234",
   "Enabled": true
   }
]

Minimum XML Team body to create a single team

<ArrayOfTeam>
  <Team>
    <Name>Team A</Name>
    <ExternalId>1234</ExternalId>
    <Enabled>true</Enabled>
  </Team>
</ArrayOfTeam>

Omitting Properties

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

Setting Custom Fields through the API

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

Team Address Properties

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

Diff Updates using the Last Updated Field

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